├── .gitignore ├── LICENSE ├── README.md ├── account.md ├── content-interaction.md ├── content.md ├── dtcp.md ├── getting-started.md ├── group.md ├── node.md ├── package.json ├── query.md ├── system.md ├── timeline.md ├── toc.js ├── token.md └── transaction.md /.gitignore: -------------------------------------------------------------------------------- 1 | .idea/ 2 | *.iml 3 | *.json 4 | node_modules/ -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | 2 | Apache License 3 | Version 2.0, January 2004 4 | http://www.apache.org/licenses/ 5 | 6 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 7 | 8 | 1. Definitions. 9 | 10 | "License" shall mean the terms and conditions for use, reproduction, 11 | and distribution as defined by Sections 1 through 9 of this document. 12 | 13 | "Licensor" shall mean the copyright owner or entity authorized by 14 | the copyright owner that is granting the License. 15 | 16 | "Legal Entity" shall mean the union of the acting entity and all 17 | other entities that control, are controlled by, or are under common 18 | control with that entity. For the purposes of this definition, 19 | "control" means (i) the power, direct or indirect, to cause the 20 | direction or management of such entity, whether by contract or 21 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 22 | outstanding shares, or (iii) beneficial ownership of such entity. 23 | 24 | "You" (or "Your") shall mean an individual or Legal Entity 25 | exercising permissions granted by this License. 26 | 27 | "Source" form shall mean the preferred form for making modifications, 28 | including but not limited to software source code, documentation 29 | source, and configuration files. 30 | 31 | "Object" form shall mean any form resulting from mechanical 32 | transformation or translation of a Source form, including but 33 | not limited to compiled object code, generated documentation, 34 | and conversions to other media types. 35 | 36 | "Work" shall mean the work of authorship, whether in Source or 37 | Object form, made available under the License, as indicated by a 38 | copyright notice that is included in or attached to the work 39 | (an example is provided in the Appendix below). 40 | 41 | "Derivative Works" shall mean any work, whether in Source or Object 42 | form, that is based on (or derived from) the Work and for which the 43 | editorial revisions, annotations, elaborations, or other modifications 44 | represent, as a whole, an original work of authorship. For the purposes 45 | of this License, Derivative Works shall not include works that remain 46 | separable from, or merely link (or bind by name) to the interfaces of, 47 | the Work and Derivative Works thereof. 48 | 49 | "Contribution" shall mean any work of authorship, including 50 | the original version of the Work and any modifications or additions 51 | to that Work or Derivative Works thereof, that is intentionally 52 | submitted to Licensor for inclusion in the Work by the copyright owner 53 | or by an individual or Legal Entity authorized to submit on behalf of 54 | the copyright owner. For the purposes of this definition, "submitted" 55 | means any form of electronic, verbal, or written communication sent 56 | to the Licensor or its representatives, including but not limited to 57 | communication on electronic mailing lists, source code control systems, 58 | and issue tracking systems that are managed by, or on behalf of, the 59 | Licensor for the purpose of discussing and improving the Work, but 60 | excluding communication that is conspicuously marked or otherwise 61 | designated in writing by the copyright owner as "Not a Contribution." 62 | 63 | "Contributor" shall mean Licensor and any individual or Legal Entity 64 | on behalf of whom a Contribution has been received by Licensor and 65 | subsequently incorporated within the Work. 66 | 67 | 2. Grant of Copyright License. Subject to the terms and conditions of 68 | this License, each Contributor hereby grants to You a perpetual, 69 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 70 | copyright license to reproduce, prepare Derivative Works of, 71 | publicly display, publicly perform, sublicense, and distribute the 72 | Work and such Derivative Works in Source or Object form. 73 | 74 | 3. Grant of Patent License. Subject to the terms and conditions of 75 | this License, each Contributor hereby grants to You a perpetual, 76 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 77 | (except as stated in this section) patent license to make, have made, 78 | use, offer to sell, sell, import, and otherwise transfer the Work, 79 | where such license applies only to those patent claims licensable 80 | by such Contributor that are necessarily infringed by their 81 | Contribution(s) alone or by combination of their Contribution(s) 82 | with the Work to which such Contribution(s) was submitted. If You 83 | institute patent litigation against any entity (including a 84 | cross-claim or counterclaim in a lawsuit) alleging that the Work 85 | or a Contribution incorporated within the Work constitutes direct 86 | or contributory patent infringement, then any patent licenses 87 | granted to You under this License for that Work shall terminate 88 | as of the date such litigation is filed. 89 | 90 | 4. Redistribution. You may reproduce and distribute copies of the 91 | Work or Derivative Works thereof in any medium, with or without 92 | modifications, and in Source or Object form, provided that You 93 | meet the following conditions: 94 | 95 | (a) You must give any other recipients of the Work or 96 | Derivative Works a copy of this License; and 97 | 98 | (b) You must cause any modified files to carry prominent notices 99 | stating that You changed the files; and 100 | 101 | (c) You must retain, in the Source form of any Derivative Works 102 | that You distribute, all copyright, patent, trademark, and 103 | attribution notices from the Source form of the Work, 104 | excluding those notices that do not pertain to any part of 105 | the Derivative Works; and 106 | 107 | (d) If the Work includes a "NOTICE" text file as part of its 108 | distribution, then any Derivative Works that You distribute must 109 | include a readable copy of the attribution notices contained 110 | within such NOTICE file, excluding those notices that do not 111 | pertain to any part of the Derivative Works, in at least one 112 | of the following places: within a NOTICE text file distributed 113 | as part of the Derivative Works; within the Source form or 114 | documentation, if provided along with the Derivative Works; or, 115 | within a display generated by the Derivative Works, if and 116 | wherever such third-party notices normally appear. The contents 117 | of the NOTICE file are for informational purposes only and 118 | do not modify the License. You may add Your own attribution 119 | notices within Derivative Works that You distribute, alongside 120 | or as an addendum to the NOTICE text from the Work, provided 121 | that such additional attribution notices cannot be construed 122 | as modifying the License. 123 | 124 | You may add Your own copyright statement to Your modifications and 125 | may provide additional or different license terms and conditions 126 | for use, reproduction, or distribution of Your modifications, or 127 | for any such Derivative Works as a whole, provided Your use, 128 | reproduction, and distribution of the Work otherwise complies with 129 | the conditions stated in this License. 130 | 131 | 5. Submission of Contributions. Unless You explicitly state otherwise, 132 | any Contribution intentionally submitted for inclusion in the Work 133 | by You to the Licensor shall be under the terms and conditions of 134 | this License, without any additional terms or conditions. 135 | Notwithstanding the above, nothing herein shall supersede or modify 136 | the terms of any separate license agreement you may have executed 137 | with Licensor regarding such Contributions. 138 | 139 | 6. Trademarks. This License does not grant permission to use the trade 140 | names, trademarks, service marks, or product names of the Licensor, 141 | except as required for reasonable and customary use in describing the 142 | origin of the Work and reproducing the content of the NOTICE file. 143 | 144 | 7. Disclaimer of Warranty. Unless required by applicable law or 145 | agreed to in writing, Licensor provides the Work (and each 146 | Contributor provides its Contributions) on an "AS IS" BASIS, 147 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 148 | implied, including, without limitation, any warranties or conditions 149 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 150 | PARTICULAR PURPOSE. You are solely responsible for determining the 151 | appropriateness of using or redistributing the Work and assume any 152 | risks associated with Your exercise of permissions under this License. 153 | 154 | 8. Limitation of Liability. In no event and under no legal theory, 155 | whether in tort (including negligence), contract, or otherwise, 156 | unless required by applicable law (such as deliberate and grossly 157 | negligent acts) or agreed to in writing, shall any Contributor be 158 | liable to You for damages, including any direct, indirect, special, 159 | incidental, or consequential damages of any character arising as a 160 | result of this License or out of the use or inability to use the 161 | Work (including but not limited to damages for loss of goodwill, 162 | work stoppage, computer failure or malfunction, or any and all 163 | other commercial damages or losses), even if such Contributor 164 | has been advised of the possibility of such damages. 165 | 166 | 9. Accepting Warranty or Additional Liability. While redistributing 167 | the Work or Derivative Works thereof, You may choose to offer, 168 | and charge a fee for, acceptance of support, warranty, indemnity, 169 | or other liability obligations and/or rights consistent with this 170 | License. However, in accepting such obligations, You may act only 171 | on Your own behalf and on Your sole responsibility, not on behalf 172 | of any other Contributor, and only if You agree to indemnify, 173 | defend, and hold each Contributor harmless for any liability 174 | incurred by, or claims asserted against, such Contributor by reason 175 | of your accepting any such warranty or additional liability. 176 | 177 | END OF TERMS AND CONDITIONS 178 | 179 | APPENDIX: How to apply the Apache License to your work. 180 | 181 | To apply the Apache License to your work, attach the following 182 | boilerplate notice, with the fields enclosed by brackets "[]" 183 | replaced with your own identifying information. (Don't include 184 | the brackets!) The text should be enclosed in the appropriate 185 | comment syntax for the file format. We also recommend that a 186 | file or class name and description of purpose be included on the 187 | same "printed page" as the copyright notice for easier 188 | identification within third-party archives. 189 | 190 | Copyright 2018 Primas Lab Foundation 191 | 192 | Licensed under the Apache License, Version 2.0 (the "License"); 193 | you may not use this file except in compliance with the License. 194 | You may obtain a copy of the License at 195 | 196 | http://www.apache.org/licenses/LICENSE-2.0 197 | 198 | Unless required by applicable law or agreed to in writing, software 199 | distributed under the License is distributed on an "AS IS" BASIS, 200 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 201 | See the License for the specific language governing permissions and 202 | limitations under the License. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Primas Node API Documentation 2 | 3 | **Status update: The APIs are finally live on the mainnet. At this moment, all the APIs writing data require the whitelisting of your address. Contact the dev team on Slack to get whitelisted.** 4 | 5 | **Join Primas developer community on Slack: [https://slack.primas.io](https://slack.primas.io/)** 6 | 7 | ### Version 8 | 9 | 3.0 10 | 11 | ### Introduction 12 | 13 | Primas is a platform for premium quality content based on DTCP (Decentralized Trusted Content Protocol). 14 | Primas uses blockchain technology to ensure the credibility of content, 15 | uses economic incentives to accelerate the generation and circulation of high-quality content, 16 | and allows readers to see personalized, high-quality content through social recommendations. 17 | Traditional Internet applications can also use APIs to access Primas, 18 | immediately gaining access to the power Primas offers. 19 | 20 | ### Primas Node 21 | 22 | Primas decentralized network is accessible through one of the Primas Nodes. 23 | And every Primas Node exposes the same collection of APIs as described in this document. 24 | To use these APIs, you need to find a live Primas Node or host one yourself. 25 | Nodes hosted by the Primas development team are accessible at: 26 | 27 | Testnet: [https://staging.primas.io](https://staging.primas.io) 28 | 29 | Mainnet Nodes: 30 | 31 | * Rigel A: [https://pstdaily.com](https://pstdaily.com) 32 | * Betelgeuse: [https://betelgeuse.primas.network](https://betelgeuse.primas.network) 33 | 34 | ### Getting Started 35 | 36 | [The getting started guide](./getting-started.md) will walk you through the general process of connecting a 37 | traditional content application to Primas. Be sure to check the [basic concepts](./dtcp.md) about Primas and 38 | DTCP before you start. 39 | 40 | ### RESTful API and Transfer Encoding 41 | 42 | APIs are served using standard RESTful methods with HTTPS. For posting, both JSON and Form-Data are 43 | supported for request body. Data sent from Primas Node is always in JSON format. 44 | 45 | To post data in JSON format, set `Content-Type` to `application/json` in http header. To post using 46 | Form-Data, set `Content-Type` to `application/x-www-form-urlencoded` or `multipart-formdata` to upload images. 47 | 48 | API should be prefixed with API version. For example, when trying to get the metadata for an article. 49 | We should call: 50 | 51 | `GET https://staging.primas.io/v3/content/1GFYUNP815RUIFDNNRKLNU78RPCFLNL5DWGT7EXODHFVRCRVXJ` 52 | 53 | The response data will always include a field `result_code` indicating the invocation status. 54 | On successful invocation `result_code` will be `0`. And the response data is in the field `data`. 55 | Otherwise `result_code` will be the corresponding error type while at the same time there will be another field 56 | `result_msg` containing the detailed description of the error. 57 | 58 | ### DTCP Metadata 59 | 60 | Primas is built upon DTCP. A lot of APIs are transferring data in the DTCP standard. Check 61 | [the DTCP brief introduction](./dtcp.md) for a detailed explanation about DTCP and its usage in Primas. 62 | 63 | ### API Batch Post 64 | 65 | APIs creating object, such as posting article, creating group, sharing article, all support batch post. Batch post can 66 | only be used with JSON format posting. To post in batch, simply pass a JSON array whose elements are the same group of 67 | metadata passed when creating a single object. The returning `data` field becomes an array containing the corresponding 68 | data for each metadata in the same order then. 69 | 70 | ### API List 71 | 72 | - [Content APIs](./content.md#content-apis) 73 | * [1. Get content metadata](./content.md#1-get-content-metadata) 74 | * [2. Get raw content](./content.md#2-get-raw-content) 75 | * [3. Post content](./content.md#3-post-content) 76 | * [4. Update content](./content.md#4-update-content) 77 | - [Content Interaction APIs](./content-interaction.md#content-interaction-apis) 78 | * [1. Get share metadata](./content-interaction.md#1-get-share-metadata) 79 | * [2. Get the shares of a group share](./content-interaction.md#2-get-the-shares-of-a-group-share) 80 | * [3. Get share reports](./content-interaction.md#3-get-share-reports) 81 | * [4. Report share](./content-interaction.md#4-report-share) 82 | * [5. Get the likes of a group share](./content-interaction.md#5-get-the-likes-of-a-group-share) 83 | * [6. Like a group share](./content-interaction.md#6-like-a-group-share) 84 | * [7. Cancel the like of a group share](./content-interaction.md#7-cancel-the-like-of-a-group-share) 85 | * [8. Get the comments of a group share](./content-interaction.md#8-get-the-comments-of-a-group-share) 86 | * [9. Get replying comments of a comment](./content-interaction.md#9-get-replying-comments-of-a-comment) 87 | * [10. Comment a group share](./content-interaction.md#10-comment-a-group-share) 88 | * [11. Update the comment of a group share](./content-interaction.md#11-update-the-comment-of-a-group-share) 89 | * [12. Delete the comment of a group share](./content-interaction.md#12-delete-the-comment-of-a-group-share) 90 | - [Group APIs](./group.md#group-apis) 91 | * [1. Get group metadata](./group.md#1-get-group-metadata) 92 | * [2. Create group](./group.md#2-create-group) 93 | * [3. Update group](./group.md#3-update-group) 94 | * [4. Dismiss group](./group.md#4-dismiss-group) 95 | * [5. Get group members](./group.md#5-get-group-members) 96 | * [6. Join group](./group.md#6-join-group) 97 | * [7. Approve or decline member application](./group.md#7-approve-or-decline-member-application) 98 | * [8. Quit group or kick member out](./group.md#8-quit-group-or-kick-member-out) 99 | * [9. Get group member whitelist](./group.md#9-get-group-member-whitelist) 100 | * [10. Add group member whitelist](./group.md#10-add-group-member-whitelist) 101 | * [11. Approve or decline group member whitelist](./group.md#11-approve-or-decline-group-member-whitelist) 102 | * [12. Quit group member whitelist](./group.md#12-quit-group-member-whitelist) 103 | * [13. Get group shares](./group.md#13-get-group-shares) 104 | * [14. Share to a group](./group.md#14-share-to-a-group) 105 | * [15. Approve or decline share application](./group.md#15-approve-or-decline-share-application) 106 | * [16. Delete group share](./group.md#16-delete-group-share) 107 | * [17. Get group avatar metadata](./group.md#17-get-group-avatar-metadata) 108 | * [18. Get group avatar raw image](./group.md#18-get-group-avatar-raw-image) 109 | - [Account APIs](./account.md#account-apis) 110 | * [1. Get account metadata](./account.md#1-get-account-metadata) 111 | * [2. Create account](./account.md#2-create-account) 112 | * [3. Update account metadata](./account.md#3-update-account-metadata) 113 | * [4. Get account credits list](./account.md#4-get-account-credits-list) 114 | * [5. Get account content list](./account.md#5-get-account-content-list) 115 | * [6. Get account groups list](./account.md#6-get-account-groups-list) 116 | * [7. Get account shares](./account.md#7-get-account-shares) 117 | * [8. Get account shares in a single group](./account.md#8-get-account-shares-in-a-single-group) 118 | * [9. Get account likes](./account.md#9-get-account-likes) 119 | * [10. Get account comments](./account.md#10-get-account-comments) 120 | * [11. Get account group applications](./account.md#11-get-account-group-applications) 121 | * [12. Get account share applications](./account.md#12-get-account-share-applications) 122 | * [13. Get account report list](./account.md#13-get-account-report-list) 123 | * [14. Get account notifications](./account.md#14-get-account-notifications) 124 | * [15. Get account avatar metadata](./account.md#15-get-account-avatar-metadata) 125 | * [16. Get account avatar raw image](./account.md#16-get-account-avatar-raw-image) 126 | - [Token APIs](./token.md#token-apis) 127 | * [1. Get account tokens data](./token.md#1-get-account-tokens-data) 128 | * [2. Get incentives list](./token.md#2-get-incentives-list) 129 | * [3. Get incentives statistics list](./token.md#3-get-incentives-statistics-list) 130 | * [4. Get incentives withdrawal list](./token.md#4-get-incentives-withdrawal-list) 131 | * [5. Withdraw incentives](./token.md#5-withdraw-incentives) 132 | * [6. Get token pre-lock list](./token.md#6-get-token-pre-lock-list) 133 | * [7. Pre-lock tokens](./token.md#7-pre-lock-tokens) 134 | * [8. Unlock pre-locked tokens](./token.md#8-unlock-pre-locked-tokens) 135 | * [9. Get token lock list](./token.md#9-get-token-lock-list) 136 | - [Timeline APIs](./timeline.md#timeline-apis) 137 | * [1. Get account timeline](./timeline.md#1-get-account-timeline) 138 | - [Query APIs](./query.md#query-apis) 139 | * [1. Query all APIs](./query.md#1-query-all-apis) 140 | - [System APIs](./system.md#system-apis) 141 | * [1. Get system parameters](./system.md#1-get-system-parameters) 142 | - [Node APIs](./node.md#node-apis) 143 | * [1. Get node list](./node.md#1-get-node-list) 144 | 145 | ### Error Code and Troubleshooting 146 | 147 | | result_code | result_msg | description | 148 | | ------------ | ------------- | ------------- | 149 | | 0 | success | Success| 150 | | 400 | client error | Client error| 151 | | 401 | invalid data | Invalid post data | 152 | | 402 | parse input JSON format error | Invalid JSON string | 153 | | 403 | client signature error | Signature verification failed | 154 | | 404 | input parameter error | Invalid parameter | 155 | | 405 | input parameter empty | Empty parameter | 156 | | 406 | nonce less than lasted | Nonce is used before | 157 | | 500 | server error | Server error | 158 | -------------------------------------------------------------------------------- /account.md: -------------------------------------------------------------------------------- 1 | # Primas Node API Documentation 2 | 3 | ## Account APIs 4 | 5 | ### 1. Get account metadata 6 | 7 | [GET] /accounts/{account_id}/metadata 8 | 9 | [GET] /accounts/{account_id}/sub/{sub_account_id}/metadata 10 | 11 | #### Response 12 | 13 | | Name | Type | Optional | Description | 14 | | -------------- | ------- | -------- | ---------------------------------------- | 15 | | id | string | n | Account id. | 16 | | address | string | n | Account address. | 17 | | title | string | n | Account name. | 18 | | abstract | string | y | Description. | 19 | | avatar | string | y | An image id used for avatar. | 20 | | creator | object | y | Creator of the [sub account](./dtcp.md#sub-accounts). | 21 | | created | integer | n | Account creation time. Unix timestamp. | 22 | | updated | integer | n | Account last updating time. Unix timestamp. | 23 | | extra | object | y | Extra metadata. | 24 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 25 | | dna | string | n | DNA of the account. | 26 | | hp | integer | n | available hp value. | 27 | | total_hp | integer | n | total hp value. | 28 | | credits | integer | n | Current credits. | 29 | | transaction_id | string | n | Latest transaction id. | 30 | 31 | `creator` object: 32 | 33 | | Name | Type | Optional | Description | 34 | | -------------- | ------- | -------- | ---------------------------------------- | 35 | | account_id | string | n | Root account id. | 36 | | account_name | string | n | Root account name. | 37 | 38 | `extra` object: 39 | 40 | | Name | Type | Optional | Description | 41 | | -------------- | ------- | -------- | ---------------------------------------- | 42 | | hash | string | y | In the case of proof of existence of secret data. The hash can be filled in this field. | 43 | 44 | #### Example 45 | 46 | ```bash 47 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 48 | 49 | {"result_code":0,"data":{"dna":"", ...}} 50 | 51 | ``` 52 | 53 | 54 | ### 2. Create account 55 | 56 | [POST] /accounts 57 | 58 | #### Request 59 | 60 | | Name | Type | Optional | Description | 61 | | -------------- | ------- | -------- | ---------------------------------------- | 62 | | version | string | n | DTCP version. Fixed to "1.0". | 63 | | type | string | n | Fixed to "object". | 64 | | tag | string | n | Fixed to "account". | 65 | | name | string | n | Name. | 66 | | abstract | string | y | Description. | 67 | | avatar | string | y | An image id used for avatar. | 68 | | creator | object | y | Creator. Required when creating [sub account](./dtcp.md#sub-accounts). | 69 | | created | integer | n | Account creation time. Unix timestamp. | 70 | | extra | object | y | Extra metadata. | 71 | | status | string | n | Fixed to "created". | 72 | | address | string | n | Ethereum address, start with "0x" | 73 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 74 | 75 | `creator` object: 76 | 77 | | Name | Type | Optional | Description | 78 | | -------------- | ------- | -------- | ---------------------------------------- | 79 | | account_id | string | n | Root account id. | 80 | | sub_account_id | string | n | Sub account id. This id is provided by the third-party application. Usually the id in the application system is used directly. | 81 | 82 | `extra` object: 83 | 84 | | Name | Type | Optional | Description | 85 | | -------------- | ------- | -------- | ---------------------------------------- | 86 | | hash | string | y | In the case of proof of existence of secret data. The hash can be filled in this field. | 87 | 88 | #### Response 89 | 90 | | Name | Type | Optional | Description | 91 | | ----- | ------ | -------- | ---------------------------------------------------------- | 92 | | id | string | y | The id of the account. No id is returned for sub accounts. | 93 | | dna | string | n | The DNA of the account. | 94 | 95 | #### Example 96 | 97 | ```bash 98 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 99 | 100 | {"result_code":0,"data":{"dna":"", ...}} 101 | 102 | ``` 103 | 104 | 105 | ### 3. Update account metadata(designing) 106 | 107 | [PUT] /accounts/{account_id} 108 | 109 | For updating, only the changed metadata need to be provided. 110 | 111 | #### Request 112 | 113 | | Name | Type | Optional | Description | 114 | | -------------- | ------- | -------- | ---------------------------------------- | 115 | | version | string | n | DTCP version. Fixed to "1.0". | 116 | | type | string | n | Fixed to "object". | 117 | | tag | string | n | Fixed to "account". | 118 | | parent_dna | string | n | The latest DNA of the account. | 119 | | status | string | n | Fixed to "updated". | 120 | | updated | integer | n | Updating time. Unix timestamp. | 121 | | name | string | y | Name. | 122 | | abstract | string | y | Description. | 123 | | avatar | string | y | An image DNA used for avatar. | 124 | | creator | object | y | Creator. Required when updating [sub account](./dtcp.md#sub-accounts). | 125 | | extra | object | y | Extra metadata. | 126 | | address | string | n | Ethereum address, start with "0x" | 127 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 128 | 129 | `creator` object: 130 | 131 | | Name | Type | Optional | Description | 132 | | -------------- | ------- | -------- | ---------------------------------------- | 133 | | account_id | string | n | Root account id. | 134 | | sub_account_id | string | n | Sub account id. | 135 | 136 | `extra` object: 137 | 138 | | Name | Type | Optional | Description | 139 | | -------------- | ------- | -------- | ---------------------------------------- | 140 | | hash | string | n | In the case of proof of existence of secret data. The hash can be filled in this field. | 141 | 142 | #### Response 143 | 144 | | Name | Type | Optional | Description | 145 | | ------------ | ------------- | ------------ | ------------- | 146 | | dna | string | n | Updated DNA of the (sub) account. | 147 | 148 | #### Example 149 | 150 | ```bash 151 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 152 | 153 | {"result_code":0,"data":{"dna":"", ...}} 154 | 155 | ``` 156 | 157 | 158 | ### 4. Get account credits list 159 | 160 | [GET] /accounts/{account_id}/credits 161 | 162 | [GET] /accounts/{account_id}/sub/{sub_account_id}/credits 163 | 164 | 165 | ### 5. Get account content list 166 | 167 | [GET] /accounts/{account_id}/content 168 | 169 | [GET] /accounts/{account_id}/sub/{sub_account_id}/content 170 | 171 | #### Query parameters 172 | 173 | | Name | Type | Optional | Description | 174 | | ------------------ | -------- | -------- | --------------------------------------------------- | 175 | | page | integer | y | Page number. Starts from 0. | 176 | | page_size | integer | y | Page size. Default to 20. | 177 | 178 | #### Response 179 | 180 | `data` is an array of [content](./content.md#1-get-content-metadata). 181 | 182 | #### Example 183 | 184 | ```bash 185 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 186 | 187 | {"result_code":0,"data":{"dna":"", ...}} 188 | 189 | ``` 190 | 191 | 192 | ### 6. Get account groups list 193 | 194 | [GET] /accounts/{account_id}/groups 195 | 196 | [GET] /accounts/{account_id}/sub/{sub_account_id}/groups 197 | 198 | #### Query parameters 199 | 200 | | Name | Type | Optional | Description | 201 | | ------------------ | -------- | -------- | --------------------------------------------------- | 202 | | page | integer | y | Page number. Starts from 0. | 203 | | page_size | integer | y | Page size. Default to 20. | 204 | 205 | #### Response 206 | 207 | `data` is an array of [group](./group.md#1-get-group-metadata). 208 | 209 | #### Example 210 | 211 | ```bash 212 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 213 | 214 | {"result_code":0,"data":{"dna":"", ...}} 215 | 216 | ``` 217 | 218 | 219 | ### 7. Get account shares 220 | 221 | [GET] /accounts/{account_id}/shares 222 | 223 | [GET] /accounts/{account_id}/sub/{sub_account_id}/shares 224 | 225 | #### Query parameters 226 | 227 | | Name | Type | Optional | Description | 228 | | ------------------ | -------- | -------- | --------------------------------------------------- | 229 | | page | integer | y | Page number. Starts from 0. | 230 | | page_size | integer | y | Page size. Default to 20. | 231 | | application_status | string | y | Status filter. "pending", "approved" or "declined". | 232 | 233 | #### Response 234 | 235 | `data` is an array of [group shares](./group.md#9-get-group-shares). 236 | 237 | #### Example 238 | 239 | ```bash 240 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 241 | 242 | {"result_code":0,"data":{"dna":"", ...}} 243 | 244 | ``` 245 | 246 | 247 | ### 8. Get account shares in a single group 248 | 249 | [GET] /accounts/{account_id}/groups/{group_id}/shares 250 | 251 | [GET] /accounts/{account_id}/sub/{sub_account_id}/groups/{group_id}/shares 252 | 253 | #### Query parameters 254 | 255 | | Name | Type | Optional | Description | 256 | | ------------------ | -------- | -------- | --------------------------------------------------- | 257 | | page | integer | y | Page number. Starts from 0. | 258 | | page_size | integer | y | Page size. Default to 20. | 259 | | application_status | string | y | Status filter. "pending", "approved" or "declined". | 260 | 261 | #### Response 262 | 263 | `data` is an array of [group shares](./group.md#9-get-group-shares). 264 | 265 | #### Example 266 | 267 | ```bash 268 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 269 | 270 | {"result_code":0,"data":{"dna":"", ...}} 271 | 272 | ``` 273 | 274 | 275 | ### 9. Get account likes 276 | 277 | [GET] /accounts/{account_id}/likes 278 | 279 | [GET] /accounts/{account_id}/sub/{sub_account_id}/likes 280 | 281 | #### Query parameters 282 | 283 | | Name | Type | Optional | Description | 284 | | ------------------ | -------- | -------- | --------------------------------------------------- | 285 | | page | integer | y | Page number. Starts from 0. | 286 | | page_size | integer | y | Page size. Default to 20. | 287 | 288 | #### Response 289 | 290 | `data` is an array of [likes](./content-interaction.md#4-get-the-likes-of-a-group-share). 291 | 292 | #### Example 293 | 294 | ```bash 295 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 296 | 297 | {"result_code":0,"data":{"dna":"", ...}} 298 | 299 | ``` 300 | 301 | 302 | ### 10. Get account comments 303 | 304 | [GET] /accounts/{account_id}/comments 305 | 306 | [GET] /accounts/{account_id}/sub/{sub_account_id}/comments 307 | 308 | #### Query parameters 309 | 310 | | Name | Type | Optional | Description | 311 | | ------------------ | -------- | -------- | --------------------------------------------------- | 312 | | page | integer | y | Page number. Starts from 0. | 313 | | page_size | integer | y | Page size. Default to 20. | 314 | 315 | #### Response 316 | 317 | `data` is an array of [comments](./content-interaction.md#7-get-the-comments-of-a-group-share). 318 | 319 | #### Example 320 | 321 | ```bash 322 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 323 | 324 | {"result_code":0,"data":{"dna":"", ...}} 325 | 326 | ``` 327 | 328 | 329 | ### 11. Get account group applications 330 | 331 | [GET] /accounts/{account_id}/applications/groups 332 | 333 | [GET] /accounts/{account_id}/sub/{sub_account_id}/applications/groups 334 | 335 | #### Query parameters 336 | 337 | | Name | Type | Optional | Description | 338 | | ------------------ | -------- | -------- | --------------------------------------------------- | 339 | | page | integer | y | Page number. Starts from 0. | 340 | | page_size | integer | y | Page size. Default to 20. | 341 | | application_status | string | y | "pending", "approved" or "declined". | 342 | 343 | #### Response 344 | 345 | `data` is an array of [group member](./group.md#5-get-group-members). 346 | 347 | #### Example 348 | 349 | ```bash 350 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 351 | 352 | {"result_code":0,"data":{"dna":"", ...}} 353 | 354 | ``` 355 | 356 | 357 | ### 12. Get account share applications 358 | 359 | [GET] /accounts/{account_id}/applications/shares 360 | 361 | [GET] /accounts/{account_id}/sub/{sub_account_id}/applications/shares 362 | 363 | #### Query parameters 364 | 365 | | Name | Type | Optional | Description | 366 | | ------------------ | -------- | -------- | --------------------------------------------------- | 367 | | page | integer | y | Page number. Starts from 0. | 368 | | page_size | integer | y | Page size. Default to 20. | 369 | | application_status | string | y | "pending", "approved" or "declined". | 370 | 371 | #### Response 372 | 373 | `data` is an array of [share](./content-interaction.md#1-get-share-metadata). 374 | 375 | #### Example 376 | 377 | ```bash 378 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 379 | 380 | {"result_code":0,"data":{"dna":"", ...}} 381 | 382 | ``` 383 | 384 | 385 | ### 13. Get account report list(designing) 386 | 387 | [GET] /accounts/{account_id}/reports 388 | 389 | [GET] /accounts/{account_id}/sub/{sub_account_id}/reports 390 | 391 | #### Query parameters 392 | 393 | | Name | Type | Optional | Description | 394 | | ------------------ | -------- | -------- | --------------------------------------------------- | 395 | | page | integer | y | Page number. Starts from 0. | 396 | | page_size | integer | y | Page size. Default to 20. | 397 | | report_status | string | y | "pending", "approved" or "declined". | 398 | 399 | #### Response 400 | 401 | `data` is an array of [report](./content-interaction.md#3-get-share-reports). 402 | 403 | #### Example 404 | 405 | ```bash 406 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 407 | 408 | {"result_code":0,"data":{"dna":"", ...}} 409 | 410 | ``` 411 | 412 | 413 | ### 14. Get account notifications(designing) 414 | 415 | [GET] /accounts/{account_id}/notifications 416 | 417 | [GET] /accounts/{account_id}/sub/{sub_account_id}/notifications 418 | 419 | The notification read status cannot be recorded in a decentralized system. To implement read status 420 | in clients, client should record a timestamp about the last time notifications are fetched. When calling 421 | API the timestamp should be passed as `start_time` to retrieve only the notifications after and mark 422 | them as unread notifications. 423 | 424 | #### Query parameters 425 | 426 | | Name | Type | Optional | Description | 427 | | ------------------ | -------- | -------- | --------------------------------------------------- | 428 | | page | integer | y | Page number. Starts from 0. | 429 | | page_size | integer | y | Page size. Default to 20. | 430 | | start_time | integer | y | List from this time. Unix timestamp. | 431 | 432 | #### Response 433 | 434 | `data` is an array of notifications: 435 | 436 | | Name | Type | Optional | Description | 437 | | -------------- | ------- | -------- | ---------------------------------------- | 438 | | type | string | n | Notification type. | 439 | | created | integer | n | Notification creation time. | 440 | | object_id | string | y | Notification related object id. | 441 | | extra | object | y | Extra metadata. | 442 | 443 | **Notification Types:** 444 | 445 | * Share 446 | * `share_liked` - Share is liked 447 | * `share_commented` - Share is commented 448 | * `share_shared` - Share is shared 449 | * Report 450 | * `report_processed` - Report is processed 451 | * Group 452 | * `member_application` - New group member application 453 | * `member_application_processed` - Group member application processed 454 | * `share_application` - New group share application 455 | * `share_application_processed` - Group share application processed 456 | * Incentives 457 | * `incentives` - Incentives calculated 458 | * `withdrawal_processed` - Withdrawal processed 459 | * Token 460 | * `pre_lock_success` - Token pre-lock success 461 | * `pre_lock_unlocked` - Token pre-lock unlocked 462 | 463 | #### Example 464 | 465 | ```bash 466 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 467 | 468 | {"result_code":0,"data":{"dna":"", ...}} 469 | 470 | ``` 471 | 472 | 473 | ### 15. Get account avatar metadata 474 | 475 | [GET] /accounts/{account_id}/avatar 476 | 477 | [GET] /accounts/{account_id}/sub/{sub_account_id}/avatar 478 | 479 | #### Response 480 | 481 | `data` is [content](./content.md#1-get-content-metadata) metadata. 482 | 483 | #### Example 484 | 485 | ```bash 486 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 487 | 488 | {"result_code":0,"data":{"dna":"", ...}} 489 | 490 | ``` 491 | 492 | 493 | ### 16. Get account avatar raw image 494 | 495 | [GET] /accounts/{account_id}/avatar/raw 496 | 497 | [GET] /accounts/{account_id}/sub/{sub_account_id}/avatar/raw 498 | 499 | Primas Node can build local cache of raw image for accessing speed. Or redirect the request to 500 | image URI for raw content directly. 501 | 502 | #### Response 503 | 504 | Response is raw image data. 505 | 506 | #### Example 507 | 508 | ```bash 509 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 510 | 511 | {"result_code":0,"data":{"dna":"", ...}} 512 | 513 | ``` 514 | 515 | ### 17. Get address metadata 516 | 517 | [GET] /main/accounts/{address}/metadata 518 | 519 | Get main account metadata by address. 520 | 521 | #### Response 522 | 523 | | Name | Type | Optional | Description | 524 | | -------------- | ------- | -------- | ---------------------------------------- | 525 | | id | string | n | Account id. | 526 | | address | string | n | Account address. | 527 | | title | string | n | Account name. | 528 | | abstract | string | y | Description. | 529 | | avatar | string | y | An image id used for avatar. | 530 | | creator | object | y | Creator of the [sub account](./dtcp.md#sub-accounts). | 531 | | created | integer | n | Account creation time. Unix timestamp. | 532 | | updated | integer | n | Account last updating time. Unix timestamp. | 533 | | extra | object | y | Extra metadata. | 534 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 535 | | dna | string | n | DNA of the account. | 536 | | hp | integer | n | available hp value. | 537 | | total_hp | integer | n | total hp value. | 538 | | credits | integer | n | Current credits. | 539 | | transaction_id | string | n | Latest transaction id. | 540 | 541 | `creator` object: 542 | 543 | | Name | Type | Optional | Description | 544 | | -------------- | ------- | -------- | ---------------------------------------- | 545 | | account_id | string | n | Root account id. | 546 | | account_name | string | n | Root account name. | 547 | 548 | `extra` object: 549 | 550 | | Name | Type | Optional | Description | 551 | | -------------- | ------- | -------- | ---------------------------------------- | 552 | | hash | string | y | In the case of proof of existence of secret data. The hash can be filled in this field. | 553 | 554 | #### Example 555 | 556 | ```bash 557 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 558 | 559 | {"result_code":0,"data":{"dna":"", ...}} 560 | 561 | ``` 562 | 563 | ### 18. Get account joined groups list 564 | 565 | [GET] /accounts/{account_id}/joined/groups 566 | 567 | [GET] /accounts/{account_id}/sub/{sub_account_id}/joined/groups 568 | 569 | #### Query parameters 570 | 571 | | Name | Type | Optional | Description | 572 | | ------------------ | -------- | -------- | --------------------------------------------------- | 573 | | page | integer | y | Page number. Starts from 0. | 574 | | page_size | integer | y | Page size. Default to 20. | 575 | 576 | #### Response 577 | 578 | `data` is an array of [group](./group.md#1-get-group-metadata). 579 | 580 | #### Example 581 | 582 | ```bash 583 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 584 | 585 | {"result_code":0,"data":{"dna":"", ...}} 586 | 587 | ``` -------------------------------------------------------------------------------- /content-interaction.md: -------------------------------------------------------------------------------- 1 | # Primas Node API Documentation 2 | 3 | ## Content Interaction APIs 4 | In Primas, content interactions(like, comment, share) can only happen 5 | in groups. And interactions in a given group are only visible to this group. 6 | When interacting with content, the corresponding group id must be provided. 7 | 8 | ### 1. Get share metadata 9 | 10 | [GET] /shares/{share_id} 11 | 12 | #### Query parameters 13 | 14 | | Name | Type | Optional | Description | 15 | | ------------------ | -------- | -------- | --------------------------------------------------- | 16 | | account_id | string | y | Account id. Account related status will be returned.| 17 | 18 | #### Response 19 | 20 | `data` is the metadata of a share: 21 | 22 | | Name | Type | Optional | Description | 23 | | -------------- | ------- | -------- | ---------------------------------------- | 24 | | id | string | n | Share id. | 25 | | src_id | string | n | Content id. | 26 | | dest_id | string | n | Group id. | 27 | | creator | object | n | Creator. | 28 | | created | integer | n | Share created time. Unix timestamp. | 29 | | updated | integer | n | Share updated time. Unix timestamp. | 30 | | extra | object | y | Extra metadata. | 31 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 32 | | dna | string | n | Latest share DNA. | 33 | | transaction_id | string | n | Latest transaction id. | 34 | 35 | `creator` object: 36 | 37 | | Name | Type | Optional | Description | 38 | | -------------- | ------- | -------- | ---------------------------------------- | 39 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 40 | | account_name | string | n | Account name. | 41 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 42 | | sub_account_name | string | y | Sub account name. | 43 | 44 | `extra` object: 45 | 46 | | Name | Type | Optional | Description | 47 | | -------------- | ------- | -------- | ----------------------------------------------- | 48 | | share_id | string | y | Parent share id. | 49 | | likes_total | integer | n | Total likes number. | 50 | | comments_total | integer | n | Total comments number. | 51 | | shares_total | integer | n | Total shares number. | 52 | | pst_total | big integer | n | Total PST earned. | 53 | | pst_updated | integer | n | Last PST updated time. Unix timestamp. | 54 | | is_liked | bool | y | Whether current account liked this share. | 55 | | content | object | n | Share related content. | 56 | | report | object | y | Report metadata. | 57 | | hp | integer | n | hp value. | 58 | 59 | `content` object contains the related [content metadata](./content.md#1-get-content-metadata). 60 | 61 | `report` object contains the related [report metadata](./content-interaction.md#3-get-share-reports). 62 | 63 | #### Example 64 | 65 | ```bash 66 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 67 | 68 | {"result_code":0,"data":{"dna":"", ...}} 69 | 70 | ``` 71 | 72 | 73 | ### 2. Get the shares of a group share 74 | 75 | [GET] /shares/{share_id}/shares 76 | 77 | #### Query parameters 78 | 79 | | Name | Type | Optional | Description | 80 | | ------------------ | -------- | -------- | --------------------------------------------------- | 81 | | page | integer | y | Page number. Starts from 0. | 82 | | page_size | integer | y | Page size. Default to 20. | 83 | | account_id | string | y | Account id filter. | 84 | 85 | #### Response 86 | 87 | `data` is an array of shares: 88 | 89 | | Name | Type | Optional | Description | 90 | | -------------- | ------- | -------- | ---------------------------------------- | 91 | | id | string | n | Share id. | 92 | | src_id | string | n | Content id. | 93 | | dest_id | string | n | Group id. | 94 | | creator | object | n | Creator. | 95 | | created | integer | n | Share created time. Unix timestamp. | 96 | | updated | integer | n | Share updated time. Unix timestamp. | 97 | | extra | object | y | Extra metadata. | 98 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 99 | | dna | string | n | Latest share DNA. | 100 | | transaction_id | string | n | Latest transaction id. | 101 | 102 | `creator` object: 103 | 104 | | Name | Type | Optional | Description | 105 | | -------------- | ------- | -------- | ---------------------------------------- | 106 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 107 | | account_name | string | n | Account name. | 108 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 109 | | sub_account_name | string | y | Sub account name. | 110 | 111 | `extra` object: 112 | 113 | | Name | Type | Optional | Description | 114 | | -------------- | ------- | -------- | ----------------------------------------------- | 115 | | share_id | string | n | Parent share id. | 116 | | likes_total | integer | n | Total likes number. | 117 | | comments_total | integer | n | Total comments number. | 118 | | shares_total | integer | n | Total shares number. | 119 | | pst_total | big integer | n | Total PST earned. | 120 | | hp | integer | n | hp value. | 121 | 122 | #### Example 123 | 124 | ```bash 125 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 126 | 127 | {"result_code":0,"data":{"dna":"", ...}} 128 | 129 | ``` 130 | 131 | 132 | ### 3. Get share reports(designing) 133 | 134 | [GET] /shares/{share_id}/reports 135 | 136 | #### Query parameters 137 | 138 | | Name | Type | Optional | Description | 139 | | ------------------ | -------- | -------- | --------------------------------------------------- | 140 | | page | integer | y | Page number. Starts from 0. | 141 | | page_size | integer | y | Page size. Default to 20. | 142 | | report_status | string | y | Status filter. "pending", "approved" or "declined". | 143 | 144 | #### Response 145 | 146 | `data` is an array of reports: 147 | 148 | | Name | Type | Optional | Description | 149 | | -------------- | ------- | -------- | ---------------------------------------- | 150 | | id | string | n | Report id. | 151 | | src_id | string | n | Account id. | 152 | | dest_id | string | n | Share id. | 153 | | creator | object | n | Creator. | 154 | | created | integer | n | Report created time. Unix timestamp. | 155 | | updated | integer | n | Report updated time. Unix timestamp. | 156 | | extra | object | n | Extra metadata. | 157 | | dna | string | n | Latest report DNA. | 158 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 159 | | transaction_id | string | n | Latest transaction id. | 160 | 161 | `creator` object: 162 | 163 | | Name | Type | Optional | Description | 164 | | -------------- | ------- | -------- | ---------------------------------------- | 165 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 166 | | account_name | string | n | Account name. | 167 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 168 | | sub_account_name | string | y | Sub account name. | 169 | 170 | `extra` object: 171 | 172 | | Name | Type | Optional | Description | 173 | | ------------- | ------- | -------- | ------------------------------------------------ | 174 | | content | string | n | Content URI. In the case of IPFS, a link starts with "ipfs://" | 175 | | content_hash | string | n | Lowercase hex string of the Keccak256 hash of the raw content. | 176 | | report_type | string | n | Report type. | 177 | | report_status | string | n | "pending", "approved" or "declined". | 178 | 179 | #### Example 180 | 181 | ```bash 182 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 183 | 184 | {"result_code":0,"data":{"dna":"", ...}} 185 | 186 | ``` 187 | 188 | 189 | ### 4. Report share(designing) 190 | 191 | [POST] /shares/{share_id}/reports 192 | 193 | #### Request 194 | 195 | | Name | Type | Optional | Description | 196 | | -------------- | ------- | -------- | ---------------------------------------- | 197 | | version | string | n | DTCP version. Fixed to "1.0". | 198 | | type | string | n | Fixed to "relation". | 199 | | tag | string | n | Fixed to "share_report". | 200 | | src_id | string | n | Account id. | 201 | | dest_id | string | n | Share id. | 202 | | creator | object | n | Creator. | 203 | | created | integer | n | Report created time. Unix timestamp. | 204 | | status | string | n | Fixed to "created". | 205 | | extra | object | n | Extra metadata. | 206 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 207 | 208 | `creator` object: 209 | 210 | | Name | Type | Optional | Description | 211 | | -------------- | ------- | -------- | ---------------------------------------- | 212 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 213 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 214 | | sub_account_name | string | y | Sub account name. For fast creation of new sub accounts. | 215 | 216 | `extra` object: 217 | 218 | | Name | Type | Optional | Description | 219 | | ------------- | ------- | -------- | ------------------------------------------------ | 220 | | content | string | n | base64 encoded report [content](./dtcp.md#content-format). | 221 | | content_hash | string | n | Lowercase hex string of the Keccak256 hash of the raw content. | 222 | | report_type | string | n | Report type. | 223 | | report_status | string | n | Fixed to "pending". | 224 | 225 | #### Response 226 | 227 | | Name | Type | Optional | Description | 228 | | ------------ | ------------- | ------------ | ------------- | 229 | | id | string | n | Report id. | 230 | | dna | string | n | Report DNA. | 231 | 232 | #### Example 233 | 234 | ```bash 235 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 236 | 237 | {"result_code":0,"data":{"dna":"", ...}} 238 | 239 | ``` 240 | 241 | 242 | ### 5. Get the likes of a group share 243 | 244 | [GET] /shares/{share_id}/likes 245 | 246 | #### Query parameters 247 | 248 | | Name | Type | Optional | Description | 249 | | ------------------ | -------- | -------- | --------------------------------------------------- | 250 | | page | integer | y | Page number. Starts from 0. | 251 | | page_size | integer | y | Page size. Default to 20. | 252 | | account_id | string | y | Account id filter. | 253 | 254 | #### Response 255 | 256 | `data` is an array of likes: 257 | 258 | | Name | Type | Optional | Description | 259 | | -------------- | ------- | -------- | ---------------------------------------- | 260 | | id | string | n | Like id. | 261 | | src_id | string | n | Account id. | 262 | | dest_id | string | n | Share id. | 263 | | hp | integer | n | hp value. | 264 | | creator | object | n | Creator. | 265 | | created | integer | n | Like created time. Unix timestamp. | 266 | | updated | integer | n | Like updated time. Unix timestamp. | 267 | | dna | string | n | Like DNA. | 268 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 269 | | transaction_id | string | n | Latest transaction id. | 270 | 271 | `creator` object: 272 | 273 | | Name | Type | Optional | Description | 274 | | -------------- | ------- | -------- | ---------------------------------------- | 275 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 276 | | account_name | string | n | Account name. | 277 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 278 | | sub_account_name | string | y | Sub account name. | 279 | 280 | #### Example 281 | 282 | ```bash 283 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 284 | 285 | {"result_code":0,"data":{"dna":"", ...}} 286 | 287 | ``` 288 | 289 | 290 | ### 6. Like a group share 291 | 292 | [POST] /shares/{share_id}/likes 293 | 294 | #### Request 295 | 296 | | Name | Type | Optional | Description | 297 | | -------------- | ------- | -------- | ---------------------------------------- | 298 | | version | string | n | DTCP version. Fixed to "1.0". | 299 | | type | string | n | Fixed to "relation". | 300 | | tag | string | n | Fixed to "share_like". | 301 | | src_id | string | n | Account id. | 302 | | dest_id | string | n | Share id. | 303 | | hp | integer | n | hp value. Greater than or equal to zero. | 304 | | creator | object | n | Creator. | 305 | | created | integer | n | Like created time. Unix timestamp. | 306 | | status | string | n | Fixed to "created". | 307 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 308 | 309 | `creator` object: 310 | 311 | | Name | Type | Optional | Description | 312 | | -------------- | ------- | -------- | ---------------------------------------- | 313 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 314 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 315 | | sub_account_name | string | y | Sub account name. For fast creation of new sub accounts. | 316 | 317 | #### Response 318 | 319 | | Name | Type | Optional | Description | 320 | | ------ | ------ | -------- | ------------- | 321 | | id | string | n | Like id. | 322 | | dna | string | n | Like dna. | 323 | 324 | #### Example 325 | 326 | ```bash 327 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 328 | 329 | {"result_code":0,"data":{"dna":"", ...}} 330 | 331 | ``` 332 | 333 | 334 | ### 7. Cancel the like of a group share(designing) 335 | 336 | [DELETE] /shares/{share_id}/likes/{like_id} 337 | 338 | #### Request 339 | 340 | | Name | Type | Optional | Description | 341 | | -------------- | ------- | -------- | ---------------------------------------- | 342 | | version | string | n | DTCP version. Fixed to "1.0". | 343 | | type | string | n | Fixed to "relation". | 344 | | tag | string | n | Fixed to "share_like". | 345 | | parent_dna | string | n | Latest DNA of the like. | 346 | | updated | integer | n | Like updated time. Unix timestamp. | 347 | | status | string | n | Fixed to "deleted". | 348 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 349 | 350 | #### Response 351 | 352 | | Name | Type | Optional | Description | 353 | | ------ | ------ | -------- | ------------- | 354 | | dna | string | n | Like dna. | 355 | 356 | #### Example 357 | 358 | ```bash 359 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 360 | 361 | {"result_code":0,"data":{"dna":"", ...}} 362 | 363 | ``` 364 | 365 | 366 | ### 8. Get the comments of a group share 367 | 368 | [GET] /shares/{share_id}/comments 369 | 370 | #### Query parameters 371 | 372 | | Name | Type | Optional | Description | 373 | | ------------------ | -------- | -------- | --------------------------------------------------- | 374 | | page | integer | y | Page number. Starts from 0. | 375 | | page_size | integer | y | Page size. Default to 20. | 376 | | account_id | string | y | Account id filter. | 377 | 378 | #### Response 379 | 380 | `data` is an array of top level comments: 381 | 382 | | Name | Type | Optional | Description | 383 | | -------------- | ------- | -------- | ---------------------------------------- | 384 | | id | string | n | Comment id. | 385 | | src_id | string | n | Account id. | 386 | | dest_id | string | n | Share id. | 387 | | hp | integer | n | hp value. | 388 | | creator | object | n | Creator. | 389 | | created | integer | n | Comment created time. Unix timestamp. | 390 | | updated | integer | n | Comment created time. Unix timestamp. | 391 | | extra | object | n | Extra metadata. | 392 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 393 | | transaction_id | string | n | Latest transaction id. | 394 | 395 | `creator` object: 396 | 397 | | Name | Type | Optional | Description | 398 | | -------------- | ------- | -------- | ---------------------------------------- | 399 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 400 | | account_name | string | n | Account name. | 401 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 402 | | sub_account_name | string | y | Sub account name. | 403 | 404 | `extra` object: 405 | 406 | | Name | Type | Optional | Description | 407 | | ----------------- | ------- | -------- | ------------------------------------------------ | 408 | | content | string | n | Comment content. | 409 | | comments | array | n | Replying comments overview. | 410 | 411 | `comments` is an array of replying comments. 412 | 413 | #### Example 414 | 415 | ```bash 416 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 417 | 418 | {"result_code":0,"data":{"dna":"", ...}} 419 | 420 | ``` 421 | 422 | 423 | ### 9. Get replying comments of a comment 424 | 425 | [GET] /comments/{comment_id}/reply 426 | 427 | #### Example 428 | 429 | ```bash 430 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 431 | 432 | {"result_code":0,"data":{"dna":"", ...}} 433 | 434 | ``` 435 | 436 | 437 | ### 10. Comment a group share 438 | 439 | [POST] /shares/{share_id}/comments 440 | 441 | The way comment content is processed is the same as [post content API](./content.md#3-post-content). 442 | 443 | #### Request 444 | 445 | | Name | Type | Optional | Description | 446 | | -------------- | ------- | -------- | ---------------------------------------- | 447 | | version | string | n | DTCP version. Fixed to "1.0". | 448 | | type | string | n | Fixed to "relation". | 449 | | tag | string | n | Fixed to "share_comment". | 450 | | src_id | string | n | Account id. | 451 | | dest_id | string | n | Share id. | 452 | | hp | integer | n | hp value. Greater than or equal to zero. | 453 | | creator | object | n | Creator. | 454 | | created | integer | n | Comment created time. Unix timestamp. | 455 | | status | string | n | Fixed to "created". | 456 | | extra | object | n | Extra metadata. | 457 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 458 | 459 | `creator` object: 460 | 461 | | Name | Type | Optional | Description | 462 | | -------------- | ------- | -------- | ---------------------------------------- | 463 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 464 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 465 | | sub_account_name | string | y | Sub account name. For fast creation of new sub accounts. | 466 | 467 | `extra` object: 468 | 469 | | Name | Type | Optional | Description | 470 | | ----------------- | ------- | -------- | ------------------------------------------------ | 471 | | parent_comment_id | string | y | Parent comment id. | 472 | | content | string | n | Comment content. | 473 | | content_hash | string | n | Lowercase hex string of the Keccak256 hash of the raw content. | 474 | 475 | #### Response 476 | 477 | | Name | Type | Optional | Description | 478 | | ------ | ------ | -------- | ------------- | 479 | | id | string | n | Comment id. | 480 | | dna | string | n | Comment dna. | 481 | 482 | #### Example 483 | 484 | ```bash 485 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 486 | 487 | {"result_code":0,"data":{"dna":"", ...}} 488 | 489 | ``` 490 | 491 | 492 | ### 11. Update the comment of a group share(designing) 493 | 494 | [PUT] /shares/{share_id}/comments/{comment_id} 495 | 496 | #### Request 497 | 498 | | Name | Type | Optional | Description | 499 | | -------------- | ------- | -------- | ---------------------------------------- | 500 | | version | string | n | DTCP version. Fixed to "1.0". | 501 | | type | string | n | Fixed to "relation". | 502 | | tag | string | n | Fixed to "share_comment". | 503 | | parent_dna | string | n | Latest comment DNA. | 504 | | creator | string | n | creator. | 505 | | updated | integer | n | Comment updated time. Unix timestamp. | 506 | | status | string | n | Fixed to "updated". | 507 | | extra | object | n | Extra metadata. | 508 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 509 | 510 | `creator` object: 511 | 512 | | Name | Type | Optional | Description | 513 | | -------------- | ------- | -------- | ---------------------------------------- | 514 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 515 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 516 | 517 | `extra` object: 518 | 519 | | Name | Type | Optional | Description | 520 | | ------------- | ------- | -------- | ------------------------------------------------ | 521 | | content | string | n | Comment content. | 522 | | content_hash | string | n | Lowercase hex string of the Keccak256 hash of the raw content. | 523 | 524 | #### Response 525 | 526 | | Name | Type | Optional | Description | 527 | | ------ | ------ | -------- | ------------- | 528 | | dna | string | n | Comment dna. | 529 | 530 | #### Example 531 | 532 | ```bash 533 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 534 | 535 | {"result_code":0,"data":{"dna":"", ...}} 536 | 537 | ``` 538 | 539 | 540 | ### 12. Delete the comment of a group share(designing) 541 | 542 | [DELETE] /shares/{share_id}/comments/{comment_id} 543 | 544 | This API can be used by both the comment creator or the group owner. 545 | 546 | When delete comment by the group owner, the group owner's info must be 547 | filled in the `creator` field and group owner's account is used to generate signature. 548 | 549 | #### Request 550 | 551 | | Name | Type | Optional | Description | 552 | | -------------- | ------- | -------- | ---------------------------------------- | 553 | | version | string | n | DTCP version. Fixed to "1.0". | 554 | | type | string | n | Fixed to "relation". | 555 | | tag | string | n | Fixed to "share_comment". | 556 | | parent_dna | string | n | Latest comment DNA. | 557 | | status | string | n | Fixed to "deleted". | 558 | | updated | integer | n | Comment updated time. Unix timestamp. | 559 | | creator | object | y | Creator. | 560 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 561 | 562 | `creator` object: 563 | 564 | | Name | Type | Optional | Description | 565 | | -------------- | ------- | -------- | ---------------------------------------- | 566 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 567 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 568 | 569 | #### Response 570 | 571 | | Name | Type | Optional | Description | 572 | | ------ | ------ | -------- | ------------- | 573 | | dna | string | n | Comment dna. | 574 | 575 | #### Example 576 | 577 | ```bash 578 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 579 | 580 | {"result_code":0,"data":{"dna":"", ...}} 581 | 582 | ``` 583 | -------------------------------------------------------------------------------- /content.md: -------------------------------------------------------------------------------- 1 | # Primas Node API Documentation 2 | 3 | ## Content APIs 4 | 5 | Content(articles and images) related APIs. Posting and reading content. 6 | 7 | ### 1. Get content metadata 8 | 9 | [GET] /content/{content_id} 10 | 11 | #### Response 12 | 13 | | Name | Type | Optional | Description | 14 | | -------------- | ------- | -------- | ---------------------------------------- | 15 | | id | string | n | Content id.| 16 | | tag | string | n | Content tag. Currently "article", "image" are supported. | 17 | | title | string | n | Content title. | 18 | | creator | object | n | Creator of the content. | 19 | | abstract | string | n | Content abstract. | 20 | | language | string | n | Content language. [RFC4646](http://www.ietf.org/rfc/rfc4646.txt) defined locales such as "en-US" | 21 | | category | string | n | Content categories. Comma separated words list. | 22 | | created | integer | n | Content creation time. Unix timestamp. | 23 | | updated | integer | n | Content last updating time. Unix timestamp. | 24 | | content | string | n | Content URI. In the case of IPFS, a link starts with "ipfs://" | 25 | | content_hash | string | n | Lowercase hex string of the Keccak256 hash of the raw content. | 26 | | license | object | y | [Content authorization license](./dtcp.md#content-licensing). | 27 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 28 | | dna | string | n | Content DNA. | 29 | | extra | object | n | Extra content metadata. | 30 | | transaction_id | string | n | Transaction id. | 31 | 32 | `creator` object: 33 | 34 | | Name | Type | Optional | Description | 35 | | -------------- | ------- | -------- | ---------------------------------------- | 36 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 37 | | account_name | string | n | Account name. Root account name in the case of Sub account posting. | 38 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 39 | | sub_account_name | string | y | Sub account name. | 40 | 41 | `extra` object: 42 | 43 | | Name | Type | Optional | Description | 44 | | -------------- | ------- | ----- | -------------------- | 45 | | ext | string | y | Image format, such as 'png', 'jpg'. Image only. | 46 | | width | integer | y | Image width in pixels. Image only. | 47 | | height | integer | y | Image height in pixels. Image only. | 48 | | size | integer | y | Image size in bytes. Image only. | 49 | | pst_total | big integer | n | Total PST earned. | 50 | | pst_updated | integer | n | Last PST updated time. Unix timestamp. | 51 | | objects | array | y | A list of images, videos, audios contained in the content. Article only. | 52 | 53 | `objects` array: 54 | 55 | | Name | Type | Optional | Description | 56 | | -------------- | ------- | ----- | -------------------- | 57 | | id | string | n | Object id. | 58 | | type | string | n | "image", "audio" or "video". | 59 | | extra | object | n | Extra metadata. | 60 | 61 | `extra` object in `resources`: 62 | 63 | | Name | Type | Optional | Description | 64 | | -------------- | ------- | ----- | -------------------- | 65 | | ext | string | y | Image format, such as 'png', 'jpg'. Image only. | 66 | | width | integer | y | Image width in pixels. Image only. | 67 | | height | integer | y | Image height in pixels. Image only. | 68 | | size | integer | y | Image size in bytes. Image only. | 69 | 70 | #### Example 71 | 72 | ```bash 73 | $ curl -x https://rigel-a.primas.network/v3/content/1GFYUNP815RUIFDNNRKLNU78RPCFLNL5DWGT7EXODHFVRCRVXJ 74 | 75 | {"result_code":0,"data":{"dna":"", ...}} 76 | 77 | ``` 78 | 79 | 80 | ### 2. Get raw content 81 | 82 | [GET] /content/{content_id}/raw 83 | 84 | Primas Node can build local cache of raw data for accessing speed. Or redirect the request to 85 | content URI directly. 86 | 87 | #### Response 88 | 89 | Response is raw image data. 90 | 91 | #### Example 92 | 93 | ```bash 94 | $ curl -x https://rigel-a.primas.network/v3/content/1GFYUNP815RUIFDNNRKLNU78RPCFLNL5DWGT7EXODHFVRCRVXJ/content 95 | 96 | {"result_code":0,"data":{"content":"..."}} 97 | 98 | ``` 99 | 100 | 101 | ### 3. Post content 102 | 103 | [POST] /content 104 | 105 | If the data is sent using JSON(Content-Type: application/json), the content field should be encoded in base64 106 | format as defined in [RFC4648](https://tools.ietf.org/html/rfc4648). This can be used to send both article and image. 107 | 108 | If the data is sent using Form-Data(Content-Type: application/x-www-form-urlencoded), the content should stay in 109 | its raw format. This is only for the article. 110 | 111 | If you're uploading an image(Content-Type: multipart-formdata), the content is the binary data of the image. 112 | 113 | #### Request 114 | 115 | | Name | Type | Optional | Description | 116 | | -------------- | ------- | -------- | ---------------------------------------- | 117 | | version | string | n | DTCP version. Fixed to "1.0". | 118 | | type | string | n | Fixed to "object". | 119 | | tag | string | n | Content type. Currently "article", "image" are supported. | 120 | | title | string | n | Content title. | 121 | | creator | object | n | Creator. | 122 | | abstract | string | n | Content abstract. | 123 | | language | string | n | Content language. [RFC4646](http://www.ietf.org/rfc/rfc4646.txt) defined locales such as "en-US" | 124 | | category | string | n | Content categories. Comma separated words list. | 125 | | created | integer | n | Content creation time. Unix timestamp. | 126 | | content | string | n | Raw [content](./content.md#content-format). | 127 | | content_hash | string | n | Lowercase hex string of the Keccak256 hash of the raw content. | 128 | | license | object | y | [Content authorization license](./dtcp.md#content-licensing). "none" is used if empty. | 129 | | status | string | n | Fixed to "created". | 130 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 131 | 132 | `creator` object: 133 | 134 | | Name | Type | Optional | Description | 135 | | -------------- | ------- | -------- | ---------------------------------------- | 136 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 137 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 138 | | sub_account_name | string | y | Sub account name. For fast creation of new sub accounts. | 139 | 140 | #### Response 141 | 142 | | Name | Type | Optional | Description | 143 | | ------------ | ------------- | ------------ | ------------- | 144 | | id | string | n | The id of the content. | 145 | | dna | string | n | The DNA of the content. | 146 | 147 | #### Example 148 | 149 | ```bash 150 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 151 | 152 | {"result_code":0,"data":{"dna":"", ...}} 153 | 154 | ``` 155 | 156 | 157 | ### 4. Update content(designing) 158 | 159 | [PUT] /content/{content_id} 160 | 161 | For updating, only the changed metadata need to be provided. 162 | 163 | #### Request 164 | 165 | | Name | Type | Optional | Description | 166 | | -------------- | ------- | -------- | ---------------------------------------- | 167 | | version | string | n | DTCP version. Fixed to "1.0". | 168 | | type | string | n | Fixed to "object". | 169 | | tag | string | n | Content type. Currently "article", "image" are supported. | 170 | | parent_dna | string | n | Latest DNA of the content. | 171 | | status | string | n | Fixed to "updated". | 172 | | updated | integer | n | Content updating time. Unix timestamp.| 173 | | title | string | y | Content title. | 174 | | abstract | string | y | Content abstract. | 175 | | category | string | y | Content categories. Comma separated words list. | 176 | | content | string | y | Raw content. | 177 | | content_hash | string | y | Lowercase hex string of the Keccak256 hash of the raw content. | 178 | | license | object | y | [Content authorization license](./dtcp.md#content-licensing). "none" is used if empty. | 179 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 180 | 181 | #### Response 182 | 183 | | Name | Type | Optional | Description | 184 | | ------------ | ------------- | ------------ | ------------- | 185 | | dna | string | n | The updated DNA of the content. | 186 | 187 | #### Example 188 | 189 | ```bash 190 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 191 | 192 | {"result_code":0,"data":{"dna":"", ...}} 193 | 194 | ``` -------------------------------------------------------------------------------- /dtcp.md: -------------------------------------------------------------------------------- 1 | # Primas Node API Documentation 2 | 3 | ## Decentralized Trusted Content Protocol 4 | 5 | ### Metadata 6 | 7 | DTCP models the digital world as a set of digital objects and the links between them. On the top level there're 8 | only 2 types of data, "object" and "link". links connect different objects together and form a network. For example, 9 | "article" is a digital object, "account" is also a digital object, "comment" is a link between an "article" 10 | and an "account". 11 | 12 | In DTCP, both objects and links are described by a collection of metadata. "article" is 13 | described with `title`, `abstract`, `content`, `author`. "comment" is described with `src_id` which points 14 | to an account and `dest_id` which points to an account, and `content` contains the comment content. 15 | 16 | DTCP is all about a series of standards of how metadata is defined for different kinds of objects and links. 17 | 18 | Primas, however, is mainly dealing with content, such as article and video, which are also objects in DTCP. 19 | A limited set of content related objects and links are also used in Primas network. 20 | 21 | ### Content Format 22 | 23 | There're different types of content such as articles, images, audios and videos. Among all the types, article is a 24 | special type which can be seen as a container for other types of content. An article may contain several images and 25 | texts at the same time. 26 | 27 | DTCP uses HTML to encode the article content, to support mixture of different content types and better display 28 | formatting. The only difference between the HTML DTCP used and any arbitrary HTML is about the links, which include 29 | hypertext links between URLs and object sources such as image sources and video sources. 30 | 31 | An important part of DTCP is the upgrade to the hypertext links. In DTCP the link is between 2 DTCP objects rather than 32 | between URLs in WWW, which gives better ability of content sourcing and content identification and interpretation. 33 | 34 | DTCP aims to replace WWW. As the Internet using WWW right now is large and filled with huge amounts of hypertext links. 35 | It is more feasible to make the upgrade a step by step process. At the beginning hypertext links and DTCP links will 36 | co-exist in DTCP. Newly created content and links will be in DTCP format. If the content contains link to URL and 37 | the link target content is not registered on DTCP network yet, the link will be saved in its original form. Otherwise if 38 | the link target content can be found on DTCP network, the link will be converted into a DTCP link whose target is a 39 | [Metadata ID](./dtcp.md#metadata-dna-and-metadata-id) rather than a URL. 40 | 41 | At this stage, it is the application's responsibility to decide which type of link to use. Primas Node provides API to 42 | fetch and check the content of a URL to see if it is a registered object on DTCP network. Application should do the 43 | converting from hypertext link to DTCP link if the content is found. Primas Node will reject the posting request if the 44 | converting is not performed. 45 | 46 | Primas network supports articles and images only at this time. Technically, before posting articles, the `` and 47 | `` elements should be checked. 48 | 49 | For `` element, the `src` attribute should be checked. If the image can be found on the DTCP network, the `src` 50 | attribute of the `` element should be replaced with the image's metadata ID: 51 | 52 | ```html 53 | 54 | ``` 55 | 56 | If the image is newly created and is uploading from local computer, the image should be post to DTCP in a separated 57 | content publishing API call, then the DTCP link in above format should be created using the returned metadata ID. 58 | 59 | Note that the image in DTCP link format cannot be directly displayed in normal web browsers. This is not a problem 60 | since the DTCP data will not be directly read by end users anyway, Primas Node will read DTCP data and transform the 61 | DTCP links into traditional hypertext links. Primas Node will also build a cache locally, the transformed links will be 62 | under Primas Node's own domain so that the access is faster. Primas Node is acting like a CDN edge server in this case. 63 | 64 | For `` hypertext links, the `href` should also be checked. The target URL should be a "reproduction" if found on the 65 | DTCP network. Then the hypertext link should be changed to a DTCP link with reproduction's metadata ID: 66 | 67 | ```html 68 | 69 | ``` 70 | 71 | The last thing to mention is that if the link is transformed to DTCP link, the original `src` and `href` attribute should 72 | not be included in the signature string. This is especially important in the scenario of web based text editors. To 73 | preview the image in the editor, `` element should contain a `src` attribute which points to the URL of image cache 74 | on Primas Node. But when signing the content, `src` attribute should be removed. 75 | 76 | ### Content Licensing 77 | 78 | In DTCP, the author could attach a license to the content to describe how the content could be used or disseminated. 79 | 80 | DTCP supports the register of all kinds of licenses while in Primas however, 81 | only 2 types of standard license is currently supported. 82 | 83 | There's a widely used license for freely content sharing 84 | called [Creative Commons](https://creativecommons.org/), or CC in short, 85 | which has a combination of different parameters to fully customize the way 86 | content can be shared. 87 | 88 | Primas supports CC 4.0 by filling "cc" in the `license.name` field. 89 | Different options can also be specified in the `license.parameters` field. 90 | 91 | ``` 92 | { 93 | "name": "cc", 94 | "version": "4.0", 95 | "parameters": [ 96 | { 97 | "name": "derivative", // Whether Derivation is allowed. 98 | "value": "y" // "y", "n" or "sa" for share-alike 99 | }, 100 | { 101 | "name": "commercial", // Whether commercial usage is allowed 102 | "value": "n" // "y" or "n" 103 | } 104 | ] 105 | } 106 | ``` 107 | 108 | Beside CC license, Primas supports commercial license as well, which allows the author 109 | to set a price on the authorization of the content: 110 | 111 | ``` 112 | { 113 | "name": "commercial", 114 | "version": "2.0", 115 | "parameters": [ 116 | { 117 | "name": "derivative", // Whether Derivation is allowed. 118 | "value": "y" // "y", "n" 119 | }, 120 | { 121 | "name": "currency", // Currency used for payment 122 | "value": "PST" // Only PST is supported in Primas network 123 | }, 124 | { 125 | "name": "price", 126 | "value": 100 127 | } 128 | ] 129 | } 130 | ``` 131 | 132 | ### Metadata DNA and Metadata ID 133 | 134 | After metadata is created and saved, we need a URI, or Uniform Resource Identifier, to find the metadata when needed. 135 | DNA, beyond all the other purposes, serves as the URI of the metadata. DNA can be generated using a set of given 136 | metadata and is unique to these metadata. 137 | 138 | The metadata cannot be modified or deleted after creation since it is recorded on the Blockchain. To implement 139 | object modification and deletion functions, DTCP adds a `status` field to record the modification status and 140 | `parent_dna` to build modification history chain for a digital object. Metadata ID is used to track the single object 141 | in its metadata chain of modification. 142 | 143 | For example, when creating an article, a set of metadata is created: 144 | 145 | ``` json 146 | 147 | { 148 | "id": "2Z2B3212", 149 | "dna": "1Q279A8D", 150 | "type": "object", 151 | "tag": "article", 152 | "title": "This is an article", 153 | "content": "This is the article content", 154 | "created": "1531897155", 155 | "status": "created" 156 | } 157 | 158 | ``` 159 | 160 | Then the article needs to be modified, instead of modifying the existing metadata, we create a new set of metadata: 161 | 162 | ``` json 163 | 164 | { 165 | "dna": "2785C422", 166 | "parent_dna": "1Q279A8D", 167 | "content": "This is the updated article content", 168 | "updated": "1532097155", 169 | "status": "updated" 170 | } 171 | 172 | ``` 173 | 174 | Note that in the updating metadata, `parent_dna` points to the previous metadata dna. And only the modified part 175 | needs to be provided. 176 | 177 | Metadata ID is only created when creating an object. It does not appear in the updating or deleting metadata. It is 178 | used to provide a consistent way of identifying an object to the applications. One can always find the same object 179 | with latest updated data using the same ID. 180 | 181 | Then the article is deleted. Another set of metadata is created: 182 | 183 | ``` json 184 | 185 | { 186 | "dna": "3696TRDF", 187 | "parent_dna": "2785C422", 188 | "updated": "1533097155", 189 | "status": "deleted" 190 | } 191 | 192 | ``` 193 | 194 | In this way, there're 2 dimensions in the network DTCP builds. The first dimension is about objects and connections 195 | between them using links. The other dimension is about the modification history of each object and link. 196 | To identify objects and links, Metadata ID is used. To track the modification history or find a dedicated version 197 | of a single object, Metadata DNA is used. 198 | 199 | DTCP standard metadata is only good for storage. It is painful if we want to provide traditional index 200 | functions to mobile apps using metadata directly. So in Primas Node, DTCP metadata is scanned at the first time 201 | to build a traditional index-friendly database, or cache, internally to speed up the access of APIs. 202 | 203 | ### Metadata Signature 204 | 205 | There's a field `signature` in the metadata standard to proof the integrity and ownership of the data. 206 | The signature in DTCP is also calculated using the same method, both the hash function and 207 | the asymmetric cryptography, which is also the same with Ethereum. 208 | 209 | **Signature String** 210 | 211 | Signature string is the JSON encoded string of the metadata. Before encoding the keys of the JSON object 212 | must be sorted in alphabetic order. And the sorting must be performed recursively on the sub objects. Arrays 213 | **DO NOT** need to be sorted. However, if the elements of an array are objects, the keys of those elements 214 | still need to be sorted, recursively. 215 | 216 | ##### Example of signature string generation 217 | 218 | **Before** 219 | 220 | ```json 221 | { 222 | "id": "bb48c151f509a1064e574dceb95e3b39eb6a1dbd9dfefa75386dc2250fdeac80", 223 | "created_at": 1527758683, 224 | "user_address": "0x251af16381A9908709DdaaA9185FB21f2811C322", 225 | "node_address": "0xd75407ad8cabeeebfed78c4f3794208b3339fbf4", 226 | "amount": "1000", 227 | "node_fee": "4", 228 | "tx_hash": "aa48c151f509a1064e574dceb95e3b39eb6a1dbd9dfefa75386dc2250fdeac80", 229 | "account_id": "0x111af16381A9908709DdaaA9185FB21f2811C3dd", 230 | "creator": { 231 | "sub_account": { 232 | "name": "movi", 233 | "id": "Sub01" 234 | }, 235 | "account_name": "kevin", 236 | "account_id": "NO134134" 237 | }, 238 | "tags": [ 239 | "wa", 240 | "ab" 241 | ], 242 | "subs": [ 243 | { 244 | "name": "movi_1", 245 | "id": "Sub01_1" 246 | }, 247 | { 248 | "name": "movi_2", 249 | "id": "Sub01_2" 250 | } 251 | ] 252 | } 253 | ``` 254 | 255 | **After Sorting** 256 | 257 | ```json 258 | { 259 | "account_id": "0x111af16381A9908709DdaaA9185FB21f2811C3dd", 260 | "amount": "1000", 261 | "created_at": 1527758683, 262 | "creator": { 263 | "account_id": "NO134134", 264 | "account_name": "kevin", 265 | "sub_account": { 266 | "id": "Sub01", 267 | "name": "movi" 268 | } 269 | }, 270 | "id": "bb48c151f509a1064e574dceb95e3b39eb6a1dbd9dfefa75386dc2250fdeac80", 271 | "node_address": "0xd75407ad8cabeeebfed78c4f3794208b3339fbf4", 272 | "node_fee": "4", 273 | "subs": [ 274 | { 275 | "id": "Sub01_1", 276 | "name": "movi_1" 277 | }, 278 | { 279 | "id": "Sub01_2", 280 | "name": "movi_2" 281 | } 282 | ], 283 | "tags": [ 284 | "wa", 285 | "ab" 286 | ], 287 | "tx_hash": "aa48c151f509a1064e574dceb95e3b39eb6a1dbd9dfefa75386dc2250fdeac80", 288 | "user_address": "0x251af16381A9908709DdaaA9185FB21f2811C322" 289 | } 290 | ``` 291 | 292 | **Final Signature String** 293 | ``` 294 | {"account_id":"0x111af16381A9908709DdaaA9185FB21f2811C3dd","amount":"1000","created_at":1527758683,"creator":{"account_id":"NO134134","account_name":"kevin","sub_account":{"id":"Sub01","name":"movi"}},"id":"bb48c151f509a1064e574dceb95e3b39eb6a1dbd9dfefa75386dc2250fdeac80","node_address":"0xd75407ad8cabeeebfed78c4f3794208b3339fbf4","node_fee":"4","subs":[{"id":"Sub01_1","name":"movi_1"},{"id":"Sub01_2","name":"movi_2"}],"tags":["wa","ab"],"tx_hash":"aa48c151f509a1064e574dceb95e3b39eb6a1dbd9dfefa75386dc2250fdeac80","user_address":"0x251af16381A9908709DdaaA9185FB21f2811C322"} 295 | ``` 296 | 297 | **SHA3 and Keccak256** 298 | 299 | DTCP uses Keccak256 as the hasing function. In most cases SHA3 and Keccak256 are the same function. 300 | However in Ethereum SHA3, which is Keccak256 is slightly different than the standard NIST-SHA3. 301 | To be compatible with Ethereum. Primas uses Keccak256 in both DTCP and Primas network. 302 | 303 | **Asymmetric Cryptography** 304 | 305 | Primas uses ECDSA-SECP256K1 to calculate the signature which is also the same with DTCP and Ethereum. 306 | The private key is a 32-byte big number. And the address is a portion of the public key. 307 | 308 | ##### Example code of signature calculation and verification in Golang 309 | ```go 310 | 311 | package main 312 | 313 | import ( 314 | "crypto/ecdsa" 315 | "encoding/hex" 316 | 317 | "github.com/ethereum/go-ethereum/crypto" 318 | "github.com/ethereum/go-ethereum/crypto/secp256k1" 319 | ) 320 | 321 | func Sign(serializedJsonString string, privateKey string) (string, error) { 322 | locPrivateKey, err := crypto.HexToECDSA(privateKey) 323 | 324 | sigStr := crypto.Keccak256([]byte(serializedJsonString)) 325 | sigBytes, err := crypto.Sign(sigStr, locPrivateKey) 326 | 327 | return hex.EncodeToString(sigBytes), err 328 | } 329 | 330 | func Verify(serializedJsonString, signature, address string) bool { 331 | msgBytes := crypto.Keccak256([]byte(serializedJsonString)) 332 | 333 | sigBytes, err := hex.DecodeString(signature) 334 | if err != nil { 335 | return false 336 | } 337 | 338 | pk, err := secp256k1.RecoverPubkey(msgBytes, sigBytes) 339 | if err != nil { 340 | return false 341 | } 342 | 343 | locPublicKey := crypto.ToECDSAPub(pk) 344 | locAddress := crypto.PubkeyToAddress(*locPublicKey) 345 | 346 | return locAddress.Hex() == address 347 | } 348 | 349 | ``` 350 | 351 | ### Metadata on Blockchain 352 | 353 | A key feature of DTCP is the tamper-proof property of metadata. All the metadata are recorded 354 | on the Blockchain. To reduce the overload on Blockchain, only the merkle root of metatdata is 355 | actually recorded on the Blockchain. There's a field `transaction_id` in every group of metadata 356 | which records the transaction that contains the merkle root of the metadata. 357 | 358 | As an example, the workflow of creating an article is as following: 359 | 360 | 1. The author, using Primas DApp, creates the article metadata, and signs it with his private key. 361 | `transaction_id`, `dna` and `id` are not included in this signature. Note that `dna` and `id` can 362 | be deterministically calculated from the metadata without `transaction_id`. the signed metadata 363 | is sent to Primas Node. 364 | 2. Primas Node receives the metadata, validates it, generates `dna` and `id`, saves them in the metadata, and 365 | returns them to the Primas DApp immediately while drop the updated metadata in a queue at the same time. 366 | 3. After a predefined period, Primas Node collects the DNAs for all the metadata in the queue, 367 | calculates the merkle root, sent the merkle root to Ethereum in a transaction. 368 | 4. Primas Node updates all the metadata in the queue with the `transaction_id`, sends them to 369 | the decentralized storage, and removes them from the queue. 370 | 371 | To verify the metadata, one needs to find all the metadata that shares the same `transaction_id` 372 | , sort all the DNAs in alphabetic order, calculate the merkle root and check if it is the same 373 | as recorded in the transaction. 374 | 375 | ### Metadata Posting 376 | 377 | Primas is built upon DCTP, for compatibility the metadata used in Primas is the same as DCTP. 378 | For all the metadata related APIs such as person registration, article posting, group creation and article sharing, 379 | the metadata in DTCP standard is post in request body. And the metadata is saved 380 | in the same format in decentralized storage. 381 | 382 | In DTCP, metadata and raw content are stored separately. The decentralized storage assigns different keys to raw content 383 | and the collection of metadata. The retrieval of complete content is divided into 2 steps. Firstly get content metadata 384 | using [Metadata ID](./dtcp.md#metadata-dna-and-metadata-id), then get the URI containing the storage key to the raw 385 | content from the metadata and get the raw content using storage key. 386 | 387 | The storage of content in DTCP is also divided into 2 steps. Firstly store the raw content, getting the storage key. 388 | Then update the metadata's `content` field with the storage key and store the metadata. 389 | 390 | For content posting APIs in Primas there's a small difference however.The raw content in its base64 encoded form 391 | should be filled in the `content` field in the post metadata. Primas Node extracts the content from metadata 392 | and saves it in decentralized storage, gets a URI(in the case of IPFS, a link starts with "ipfs://"), 393 | and puts the URI in the `content` field and saves the metadata to decentralized storage then. 394 | 395 | ### Sub Accounts 396 | 397 | Primas supports the integration with traditional centralized applications. 398 | Such applications could use APIs to connect to Primas Node(both self-hosted or public one) 399 | and gain full power of Primas in a second. 400 | 401 | Authentication in a decentralized system is done by digital signatures, 402 | which means in a simplest setup applications connecting to Primas needs to 403 | create a public/private keypair for each user, which makes the integration 404 | much harder(applications need to handle the private key properly, whether using 405 | a KMS infrastructure and taking the risk of losing all keys, or giving the keys to 406 | users and taking the complains about lost keys cannot be found.) while at the 407 | same time limits the customization of the economic model and tokens(PST incentives 408 | are calculated and distributed directly to end users). 409 | 410 | Primas provides the sub account system to make the integration process less painful 411 | and support more ways integration can be designed. 412 | 413 | In the sub account integration setup, only one public/private keypair needs to be created 414 | for the application. The keypair is attached to a "root account" representing the identity 415 | of the application. When posting content on behalf of a user in the application, 416 | the application signs the request using its root account private key and passes the user's id 417 | in the application as a parameter. Primas then creates a "sub account" for this user 418 | which is attached to the root account. Every time the application wants to do something on 419 | behalf of the same user, it must provide the same user's id parameter and signs it using the 420 | root account private key. 421 | 422 | In DTCP layer, however, the sub account and root account are both "account" object with only 423 | one difference that sub account has no public key attached. There's a "link" object between 424 | root and sub account establishing the relation between these 2 accounts. This gives the 425 | opportunity of "upgrading" the sub account to a root account or binding different accounts 426 | together in the future. 427 | 428 | All the tokens are locked on the root account. If a sub account posts an article, 2 PST will be 429 | locked on the root account. For large scale applications they must ensure enough token pre-lock 430 | on the root account. The incentives are calculated on the sub account level, which means application 431 | can get the daily incentives record for each application user. **But the PST incentives will be distributed 432 | to the root account**. 433 | 434 | Sub account system supports the isolation of PST and incentives model from the application's own. 435 | PST can be only visible to the application's root account while users of the application know nothing 436 | about it. Applications can build their own economic model and issue their own tokens on top of 437 | integration with Primas. 438 | -------------------------------------------------------------------------------- /getting-started.md: -------------------------------------------------------------------------------- 1 | # Primas Node API Documentation 2 | 3 | ## Getting Started Guide 4 | 5 | This document describes the general steps required to connect to Primas network using API. The applications who connect 6 | to Primas network can be categorized into 2 types: 7 | 8 | 1. The client application. Such as Primas Android and iOS DApp. These applications are usually used by only one user. 9 | 2. The platform application. Such as a UGC platform. These applications are used by multiple users and have their own 10 | user account system. 11 | 12 | ### 1. Prepare the root account 13 | 14 | For client applications, this is the crypto account representing the end-user and is the only account required. 15 | 16 | For platform applications, this is the crypto account representing the platform. For each of the platform users, 17 | there is still a sub account needed. 18 | 19 | To make the life easier for platform applications, there's only one crypto account(a public/private keypair) that is 20 | required to connect to Primas. This account is used by the platform to sign requests. The users of the platform don't 21 | need to have their own crypto account. They share the platform's crypto account and the user IDs on the platform are 22 | used to create sub accounts on Primas network. 23 | 24 | The crypto account is nothing more than a normal Ethereum account, with enough PST in it of course. All the locks 25 | and consumptions of PST of the platform users will be counted on the platform account. For example, a UGC 26 | platform has 10 users in total, and today there're 2 articles post by 2 users. There will be a lock of 4 PSTs for 27 | 7 days on the platform account. 28 | 29 | Platform application usually needs to sign the request online, a proper design of offline signing mechanism is still 30 | needed to protect the private key. This is already less work comparing to generating keypair for every single user. 31 | The crypto account should be created on the signing machine and never touch the Internet. 32 | 33 | [Primas Offline Signer](https://github.com/primasio/primas-offline-signer) can be used to implement an offline signing 34 | machine. To generate a new Ethereum account, type the following command in the console: 35 | 36 | ```bash 37 | $ ./offline-signer account --passwd "password" 38 | 39 | Account created successfully 40 | Account Address: 0x284111d30E36029B6Aa9245d******Bb4b83e420A 41 | Account Mnemonic: cover **** drum defense **** curious **** very muscle **** okay slab 42 | Account Keystore: keystore:///Users/barry/gopath/src/github.com/kooksee/pstoff/kdata/keystore/UTC--2018-08-03T05-13-24.876762121Z--284111d30e36029b6aa9245d******bb4b83e420a 43 | 44 | ``` 45 | 46 | Now we have the mnemonic words of the private key and the account address. Write down the mnemonic words on a paper 47 | and keep it in a safe place. 48 | 49 | Let's skip the steps where we go to a token exchange who has PST listed and buy some PSTs and withdraw those tokens 50 | into the account we just created. 51 | 52 | The next step is registering the account on the Primas network. This can be done using Primas API. We have SDKs 53 | prepared for different languages. In this guide we use the [NodeJS SDK](https://github.com/primasio/primas-api-sdk-js). 54 | 55 | ```js 56 | /** 57 | * Create root account 58 | */ 59 | 60 | var Primas = require("primas-sdk-nodejs"); 61 | 62 | // We will not use offline signing mechanism for easier understanding of the process. 63 | // The keystore is placed under a folder named "keystore" in the root folder of the project 64 | // which is also the default config. 65 | 66 | // The keystore is encrypted with a passphrase. 67 | 68 | var client = new Primas({ 69 | address: "", 70 | passphrase: "", 71 | node: "https://rigel-a.primas.network" 72 | }); 73 | 74 | var account = client.Account.create({ 75 | name: "", 76 | // avatar: "", // Avatar should be a metadata ID which can only be uploaded after the account creation. 77 | address: "" 78 | }); 79 | 80 | account.send(function(err, res) { 81 | 82 | if (err) { 83 | // handle error 84 | return; 85 | } 86 | 87 | // The response contains the account id and metadata dna 88 | 89 | console.log(res.id); 90 | console.log(res.dna); 91 | }) 92 | 93 | ``` 94 | 95 | After that the root account is fully prepared and can be used to sign API requests. 96 | 97 | ### 2. User sign up 98 | 99 | **This is only for the platform applications.** 100 | 101 | Platforms usually assign each of their users a numeric unique ID in the system. This ID, together with the root account 102 | ID, is used to identify the platform user in Primas network. 103 | 104 | For some platforms, there's not too much profile data needed for the user in the Primas network. The name and id 105 | might already be sufficient. In this case, we don't even need to have a separated sign up process. We can already use 106 | the content publishing API to post content on behalf of the user, with the id and name of the user attached in the 107 | request. The user account will be created automatically. 108 | 109 | However, for other applications that have a rich set of user profile, such as applications that store users' resume. 110 | We need to create user's account separately to upload the resume data. If the application needs to keep the detailed 111 | profile data safe while at the same time create proof-of-existence of the data, it can upload only the hash of the 112 | profile data to Primas network. 113 | 114 | ```js 115 | /** 116 | * Create sub(user) account 117 | */ 118 | 119 | var account = client.Account.create({ 120 | name: "", 121 | creator: { 122 | account_id: "", // The platform ID we received in the previous step. 123 | sub_account_id: "" // This id is used together to identify the user on Primas network. 124 | }, 125 | extra: { 126 | hash: "" // In case of sensitive user data that needs proof-of-existence, the data hash can be stored here. 127 | } 128 | } 129 | ); 130 | account.send(function(err, res) { 131 | if (err) { 132 | // handle error 133 | return; 134 | } 135 | 136 | // For sub accounts. No account id is returned at the moment. 137 | // The sub account is identified user root account id and user id on the platform. 138 | // console.log(res.id); 139 | 140 | console.log(res.dna); 141 | }) 142 | 143 | ``` 144 | 145 | ### 3. Post content 146 | 147 | Now we can post content to Primas network. 148 | 149 | Primas supports different kinds of content, such as articles, images, videos and audios. Among which the article type 150 | serves as a container for texts and other types of content. For details about how content is stored in article type, 151 | please refer to [Content Format](./dtcp.md#content-format). 152 | 153 | **For client applications that don't have their own servers, the content posting will be an interactive process:** 154 | 155 | #### User uploads an image 156 | 157 | 1. The image should be directly post to [content posting API](./content.md#3-post-content). 158 | Primas Node checks the image hash to see if there's a same image in the DTCP network before. If there exists one, the 159 | [Metadata ID](./dtcp.md#metadata-dna-and-metadata-id) of the existing image is returned, otherwise Primas Node uploads 160 | the image to DTCP network and returns its Metadata ID. 161 | 162 | 2. Primas Node will cache the image and generate a URL for the image and return the URL together with Metadata ID. This 163 | URL can be inserted into the `src` attribute of `` to display the image in the text editor: 164 | 165 | `` 166 | 167 | #### User inserts `` element directly 168 | 169 | 1. The `src` attribute of the `` element should be checked in DTCP network using 170 | [query content API](./query.md#2-find-content-using-url-or-hash). 171 | 172 | 2. If the image is found, the `` element should be upgraded to DTCP link: 173 | 174 | `` 175 | 176 | #### User creates hypertext link 177 | 178 | 1. The `href` attribute of the `a` element should be checked using 179 | [query reproduction API](./query.md#3-find-reproductions-using-url). 180 | 181 | 2. If the reproduction is found, the hypertext link should be upgraded: 182 | 183 | `` 184 | 185 | When user submits the content, The content is post to [content posting API](./content.md#3.-post-content) using SDK. 186 | The SDK will automatically removes `src` attribute of the `` element and `href` in the `` element from the 187 | DTCP links(those attributes in traditional hypertext links will be preserved) and then signs the content and posts it 188 | to Primas API. 189 | 190 | **For platform applications, the user interface to handle content editing and image uploading should be fully functional 191 | already. The content posting to Primas API is much easier with the help of the SDK, and the posting can be built as an 192 | async operation to avoid blocking:** 193 | 194 | ```js 195 | /** 196 | * Post content with embedded images 197 | */ 198 | 199 | var htmlContent = '

The original HTML content.

'; 200 | 201 | // Upgrade DTCP links before posting 202 | // This function call might take a long while to complete. 203 | client.Content.upgradeDTCPLinks(htmlContent, function (err, content) { 204 | 205 | // The content will become something like this: 206 | //

The original HTML content.

207 | 208 | if (err) { 209 | // handle error 210 | return; 211 | } 212 | 213 | // The content will be processed again 214 | // to remove the `src` and `href` of DTCP links. 215 | // Then the content hash is calculated. 216 | // After that the whole metadata is signed and sent to the API. 217 | 218 | var content = client.Content.create({ 219 | title: "
", 220 | creator: { 221 | account_id: "", 222 | sub_account_id: "", 223 | 224 | // If the sub account is not registered separated before, 225 | // provide the name here and it will be created automatically. 226 | // sub_account_name: "" 227 | }, 228 | abstract: "
", 229 | language: "en-US", 230 | category: "
", 231 | content: content 232 | }) 233 | 234 | content.send(function (err, res) { 235 | 236 | if (err) { 237 | // handle error 238 | return; 239 | } 240 | 241 | // Article ID and DNA will be returned. 242 | 243 | console.log(res.id); 244 | console.log(res.dna); 245 | }) 246 | }); 247 | ``` 248 | 249 | Note that in this case, the `src` and `href` attribute will **NOT** be replaced by the cached version on Primas Node 250 | and the original URL points to the UGC platform will be preserved. 251 | 252 | ### 4. Create a group 253 | 254 | There're different options to customize the group rules when creating the group: 255 | 256 | 1. How member could join the group 257 | 258 | a. Freely join 259 | 260 | b. Apply to join 261 | 262 | c. Pay to join (coming soon) 263 | 264 | 2. How content could be shared in the group 265 | 266 | a. Freely share 267 | 268 | b. Apply to share 269 | 270 | c. Whitelisted member can share 271 | 272 | d. Pay to share (coming soon) 273 | 274 | ```js 275 | /** 276 | * Creat a group 277 | */ 278 | 279 | var group = client.Group.create({ 280 | title: "", 281 | creator: { 282 | account_id: "", 283 | sub_account_id: "", 284 | 285 | // If the sub account is not registered separated before, 286 | // provide the name here and it will be created automatically. 287 | // sub_account_name: "" 288 | }, 289 | avatar: "", 290 | abstract: "", 291 | language: "en-US", 292 | category: "
", 293 | extra: { 294 | allow_join: "all", // How member could join the group. "all" or "application". 295 | allow_post: "all" // How content could be shared in the group. "all", "none" or "application". 296 | } 297 | }); 298 | 299 | group.send(function (err, res) { 300 | if (err) { 301 | // handle error 302 | return; 303 | } 304 | // group ID and DNA will be returned. 305 | 306 | console.log(res.id); 307 | console.log(res.dna); 308 | }) 309 | ``` 310 | 311 | ### 5. Join a group 312 | 313 | The joining operation is a little bit different according to the group joining rules. The API is always the same. If the 314 | group requires application before joining, the `application_status` parameter should be set to "pending" in the API call. 315 | 316 | ```js 317 | /** 318 | * Join a group 319 | */ 320 | 321 | var group = client.Group.join("", { 322 | title: "", 323 | src_id: "", 324 | dest_id: "", 325 | creator: { 326 | account_id: "", 327 | sub_account_id: "", 328 | 329 | // If the sub account is not registered separated before, 330 | // provide the name here and it will be created automatically. 331 | // sub_account_name: "" 332 | }, 333 | 334 | // If the group requires application before joining, the following parameters should be set: 335 | extra: { 336 | application_status: "pending", 337 | application_expire: Date.now() + 24 * 3600 // The application will expire after 24 hours. 338 | } 339 | }); 340 | 341 | group.send(function (err, res) { 342 | if (err) { 343 | // handle error 344 | return; 345 | } 346 | 347 | // group member ID and DNA will be returned 348 | 349 | console.log(res.id); 350 | console.log(res.dna); 351 | }) 352 | ``` 353 | 354 | ### 6. Share content to a group 355 | 356 | The share can be created from content directly, or from another share. There's a field named `share_id` in the `extra` 357 | field of a share to trace where this share came from. If the share is from the content directly, `share_id` in `extra` 358 | will be null. 359 | 360 | If the group requires application before sharing, set the `application_status` field. 361 | 362 | ```js 363 | /** 364 | * Share to a group 365 | */ 366 | 367 | // Group requires application 368 | var group = client.Group.createShare("", { 369 | src_id: "", 370 | dest_id: "", 371 | creator: { 372 | account_id: "", 373 | sub_account_id: "", 374 | 375 | // If the sub account is not registered separated before, 376 | // provide the name here and it will be created automatically. 377 | // sub_account_name: "" 378 | }, 379 | 380 | 381 | extra: { 382 | // If the share is created from another share, the following parameters should be set: 383 | share_id: "", 384 | 385 | // If the group requires application to share, the following parameters should be set: 386 | application_status: "pending", 387 | application_expire: Date.now() + 24 * 3600 // The application will expire after 24 hours. 388 | } 389 | 390 | }); 391 | group.send(function (err, res) { 392 | if (err) { 393 | // handle error 394 | return; 395 | } 396 | 397 | // Share ID and DNA will be returned 398 | 399 | console.log(res.id); 400 | console.log(res.dna); 401 | }) 402 | ``` 403 | 404 | ### 7. Discuss about the content 405 | 406 | More precisely, it is discussing about the **shares** rather than the content, since content cannot be seen or liked 407 | or commented until it is shared to a group. So the discussion happens on the share in the group. And the discussion is 408 | only visible in the group. 409 | 410 | ```js 411 | /** 412 | * Like a share 413 | */ 414 | 415 | var ci = client.ContentInteraction.createLike("", { 416 | src_id: "", 417 | dest_id: "", 418 | creator: { 419 | account_id: "", 420 | sub_account_id: "", 421 | 422 | // If the sub account is not registered separated before, 423 | // provide the name here and it will be created automatically. 424 | // sub_account_name: "" 425 | } 426 | }); 427 | ci.send(function (err, res) { 428 | if (err) { 429 | // handle error 430 | return; 431 | } 432 | // handle res 433 | }) 434 | 435 | /** 436 | * Comment on a share 437 | */ 438 | 439 | var ci = client.ContentInteraction.createComment("", { 440 | src_id: "", 441 | dest_id: "", 442 | creator: { 443 | account_id: "", 444 | sub_account_id: "", 445 | 446 | // If the sub account is not registered separated before, 447 | // provide the name here and it will be created automatically. 448 | // sub_account_name: "" 449 | }, 450 | extra: { 451 | parent_comment_id: "", // If this comment is a reply to another comment, the comment id should be set. 452 | content: "" // HTML format comment content, DTCP links still need to be upgraded. 453 | } 454 | }); 455 | ci.send(function (err, res) { 456 | if (err) { 457 | // handle error 458 | return; 459 | } 460 | // Comment ID and DNA is returned 461 | 462 | console.log(res.id); 463 | console.log(res.dna); 464 | }) 465 | ``` 466 | -------------------------------------------------------------------------------- /group.md: -------------------------------------------------------------------------------- 1 | # Primas Node API Documentation 2 | 3 | ## Group APIs 4 | 5 | ### 1. Get group metadata 6 | 7 | [GET] /groups/{group_id} 8 | 9 | #### Query parameters 10 | 11 | | Name | Type | Optional | Description | 12 | | ------------------ | -------- | -------- | --------------------------------------------------- | 13 | | account_id | string | y | Account id. Account related status will be returned.| 14 | 15 | #### Response 16 | 17 | | Name | Type | Optional | Description | 18 | | -------------- | ------- | -------- | ---------------------------------------- | 19 | | id | string | n | Group id. | 20 | | title | string | n | Group title. | 21 | | creator | object | n | Creator. | 22 | | avatar | string | n | An image id used for avatar. | 23 | | abstract | string | n | Group introduction. | 24 | | language | string | n | Group language. [RFC4646](http://www.ietf.org/rfc/rfc4646.txt) defined locales such as "en-US" | 25 | | category | string | n | Group categories. Comma separated words list. | 26 | | created | integer | n | Group creation time. Unix timestamp. | 27 | | updated | integer | n | Group last updating time. Unix timestamp. | 28 | | extra | object | n | Extra metadata. | 29 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 30 | | dna | string | n | Group DNA. | 31 | | transaction_id | string | n | Latest transaction id. | 32 | 33 | `creator` object: 34 | 35 | | Name | Type | Optional | Description | 36 | | -------------- | ------- | -------- | ---------------------------------------- | 37 | | account_id | string | n | Root account id. | 38 | | account_name | string | n | Root account name. | 39 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 40 | | sub_account_name | string | y | Sub account name. | 41 | 42 | `extra` object: 43 | 44 | | Name | Type | Optional | Description | 45 | | -------------- | ------- | -------- | ---------------------------------------- | 46 | | allow_join | string | n | Joining group control. "all" or "application". | 47 | | allow_post | string | n | Posting control. "all", "none", "application". | 48 | | members_total | integer | n | Total members number. | 49 | | shares_total | integer | n | Total shares number. | 50 | | account_role | string | y | Member status of current account. "owner", "member", "applicant" or "none". | 51 | | members | array | n | Members overview. An array of [account metadata](./account.md#1-get-account-metadata). | 52 | 53 | 54 | ### 2. Create group 55 | 56 | [POST] /groups 57 | 58 | #### Request 59 | 60 | | Name | Type | Optional | Description | 61 | | -------------- | ------- | -------- | ---------------------------------------- | 62 | | version | string | n | DTCP version. Fixed to "1.0". | 63 | | type | string | n | Fixed to "object". | 64 | | tag | string | n | Fixed to "group". | 65 | | title | string | n | Group title. | 66 | | creator | object | n | Creator. | 67 | | avatar | string | y | An image id used for avatar. | 68 | | abstract | string | n | Group introduction. | 69 | | language | string | n | Group language. [RFC4646](http://www.ietf.org/rfc/rfc4646.txt) defined locales such as "en-US" | 70 | | category | string | n | Group categories. Comma separated words list. | 71 | | created | integer | n | Group creation time. Unix timestamp. | 72 | | extra | object | n | Extra metadata. | 73 | | status | string | n | Fixed to "created". | 74 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 75 | 76 | `creator` object: 77 | 78 | | Name | Type | Optional | Description | 79 | | -------------- | ------- | -------- | ---------------------------------------- | 80 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 81 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 82 | | sub_account_name | string | y | Sub account name. For fast creation of new sub accounts. | 83 | 84 | `extra` object: 85 | 86 | | Name | Type | Optional | Description | 87 | | -------------- | ------- | -------- | ---------------------------------------- | 88 | | allow_join | string | n | Joining group control. "all" or "application". | 89 | | allow_post | string | n | Posting control. "all", "none", "application". | 90 | 91 | #### Response 92 | 93 | | Name | Type | Optional | Description | 94 | | ------------ | ------------- | ------------ | ------------- | 95 | | id | string | n | The id of the group. | 96 | | dna | string | n | The DNA of the group. | 97 | 98 | #### Example 99 | 100 | ```bash 101 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 102 | 103 | {"result_code":0,"data":{"dna":"", ...}} 104 | 105 | ``` 106 | 107 | 108 | ### 3. Update group(designing) 109 | 110 | [PUT] /groups/{group_id} 111 | 112 | For updating, only the changed metadata need to be provided. 113 | 114 | #### Request 115 | 116 | | Name | Type | Optional | Description | 117 | | -------------- | ------- | -------- | ---------------------------------------- | 118 | | version | string | n | DTCP version. Fixed to "1.0". | 119 | | type | string | n | Fixed to "object". | 120 | | tag | string | n | Fixed to "group". | 121 | | parent_dna | string | n | The latest DNA of the group. | 122 | | status | string | n | Fixed to "updated". | 123 | | updated | integer | n | Group update time. Unix timestamp. | 124 | | title | string | y | Group title. | 125 | | avatar | string | y | An image id used for avatar. | 126 | | abstract | string | y | Group introduction. | 127 | | language | string | y | Group language. [RFC4646](http://www.ietf.org/rfc/rfc4646.txt) defined locales such as "en-US" | 128 | | category | string | y | Group categories. Comma separated words list. | 129 | | extra | object | y | Extra metadata. | 130 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 131 | 132 | `extra` object: 133 | 134 | | Name | Type | Optional | Description | 135 | | -------------- | ------- | -------- | ---------------------------------------- | 136 | | allow_join | string | y | Joining group control. "all" or "application". | 137 | | allow_post | string | y | Posting control. "all", "none", "application". | 138 | 139 | #### Response 140 | 141 | | Name | Type | Optional | Description | 142 | | ------------ | ------------- | ------------ | ------------- | 143 | | dna | string | n | The new DNA of the group. | 144 | 145 | #### Example 146 | 147 | ```bash 148 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 149 | 150 | {"result_code":0,"data":{"dna":"", ...}} 151 | 152 | ``` 153 | 154 | 155 | ### 4. Dismiss group(designing) 156 | 157 | [DELETE] /groups/{group_id} 158 | 159 | #### Request 160 | 161 | | Name | Type | Optional | Description | 162 | | -------------- | ------- | -------- | ---------------------------------------- | 163 | | version | string | n | DTCP version. Fixed to "1.0". | 164 | | type | string | n | Fixed to "object". | 165 | | tag | string | n | Fixed to "group". | 166 | | parent_dna | string | n | The latest DNA of the group. | 167 | | status | string | n | Fixed to "deleted". | 168 | | updated | integer | n | Group updating time. Unix timestamp. | 169 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 170 | 171 | #### Response 172 | 173 | | Name | Type | Optional | Description | 174 | | ---- | ------ | -------- | ----------- | 175 | | dna | string | n | Group DNA. | 176 | 177 | #### Example 178 | 179 | ```bash 180 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 181 | 182 | {"result_code":0,"data":{"dna":"", ...}} 183 | 184 | ``` 185 | 186 | 187 | ### 5. Get group members 188 | 189 | [GET] /groups/{group_id}/members 190 | 191 | #### Query parameters 192 | 193 | | Name | Type | Optional | Description | 194 | | ------------------ | -------- | -------- | --------------------------------------------------- | 195 | | page | integer | y | Page number. Starts from 0. | 196 | | page_size | integer | y | Page size. Default to 20. | 197 | | application_status | string | y | Status filter. "pending", "approved" or "declined". | 198 | 199 | #### Response 200 | 201 | Response `data` is an array whose elements contain: 202 | 203 | | Name | Type | Optional | Description | 204 | | ------------------- | ------- | -------- | ----------- | 205 | | id | string | n | Group member id. | 206 | | src_id | string | n | Account id. Root account id in the case of [Sub account](./dtcp.md#sub-accounts). | 207 | | dest_id | string | n | Group id. | 208 | | creator | object | n | Creator. | 209 | | created | integer | n | Member joining time. Unix timestamp. | 210 | | updated | integer | n | Member updating time. Unix timestamp. | 211 | | extra | object | y | Extra metadata. | 212 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 213 | | dna | string | n | Group member DNA. | 214 | | transaction_id | string | n | Latest transaction id. | 215 | | account | object | n | Related member account. | 216 | 217 | `creator` object: 218 | 219 | | Name | Type | Optional | Description | 220 | | -------------- | ------- | -------- | ---------------------------------------- | 221 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 222 | | account_name | string | n | Account name. | 223 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 224 | | sub_account_name | string | y | Sub account name. For fast creation of new sub accounts. | 225 | 226 | `extra` object: 227 | 228 | | Name | Type | Optional | Description | 229 | | -------------- | ------- | -------- | ----------------------------------------------- | 230 | | application_status | string | n | "pending", "approved" or "declined". | 231 | 232 | `account` object: 233 | 234 | | Name | Type | Optional | Description | 235 | | -------------- | ------- | -------- | ---------------------------------------- | 236 | | id | string | n | Account id. | 237 | | address | string | n | Account address. | 238 | | title | string | n | Account name. | 239 | | abstract | string | y | Description. | 240 | | avatar | string | y | An image DNA used for avatar. | 241 | | creator | object | y | Creator. Provided when this account is a [sub account](./dtcp.md#sub-accounts). | 242 | | created | string | n | Account creation time. Unix timestamp. | 243 | | updated | string | n | Account last updating time. Unix timestamp. | 244 | | extra | object | y | Extra metadata. | 245 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 246 | | dna | string | n | DNA of the account. | 247 | 248 | #### Example 249 | 250 | ```bash 251 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 252 | 253 | {"result_code":0,"data":{"dna":"", ...}} 254 | 255 | ``` 256 | 257 | 258 | ### 6. Join group 259 | 260 | [POST] /groups/{group_id}/members 261 | 262 | #### Request 263 | 264 | | Name | Type | Optional | Description | 265 | | -------------- | ------- | -------- | ---------------------------------------- | 266 | | version | string | n | DTCP version. Fixed to "1.0". | 267 | | type | string | n | Fixed to "relation". | 268 | | tag | string | n | Fixed to "group_member". | 269 | | src_id | string | n | Account id. Root account id in the case of [Sub account](./dtcp.md#sub-accounts). | 270 | | dest_id | string | n | Group id. | 271 | | creator | object | n | Creator. | 272 | | created | integer | n | Member joining time. Unix timestamp. | 273 | | status | string | n | Fixed to "created". | 274 | | extra | object | y | Extra metadata. | 275 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 276 | 277 | `creator` object: 278 | 279 | | Name | Type | Optional | Description | 280 | | -------------- | ------- | -------- | ---------------------------------------- | 281 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 282 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 283 | | sub_account_name | string | y | Sub account name. For fast creation of new sub accounts. | 284 | 285 | `extra` object: 286 | 287 | | Name | Type | Optional | Description | 288 | | -------------- | ------- | -------- | ----------------------------------------------- | 289 | | application_status | string | n | For group requiring application. Fill "pending". | 290 | | application_expire | integer | n | Application expiration time. | 291 | 292 | #### Response 293 | 294 | | Name | Type | Optional | Description | 295 | | ------------ | ------------- | ------------ | ------------- | 296 | | id | string | n | Group member id. | 297 | | dna | string | n | Group member DNA. | 298 | 299 | #### Example 300 | 301 | ```bash 302 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 303 | 304 | {"result_code":0,"data":{"dna":"", ...}} 305 | 306 | ``` 307 | 308 | 309 | ### 7. Approve or decline member application 310 | 311 | [PUT] /groups/{group_id}/members/{group_member_id} 312 | 313 | #### Request 314 | 315 | | Name | Type | Optional | Description | 316 | | -------------- | ------- | -------- | ---------------------------------------- | 317 | | version | string | n | DTCP version. Fixed to "1.0". | 318 | | type | string | n | Fixed to "relation". | 319 | | tag | string | n | Fixed to "group_member". | 320 | | parent_dna | string | n | Latest group member DNA. | 321 | | status | string | n | Fixed to "updated". | 322 | | updated | integer | n | Member updating time. Unix timestamp. | 323 | | creator | object | n | Creator. Group owner. | 324 | | extra | object | n | Extra metadata. | 325 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 326 | 327 | `creator` object: 328 | 329 | | Name | Type | Optional | Description | 330 | | -------------- | ------- | -------- | ---------------------------------------- | 331 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 332 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 333 | 334 | `extra` object: 335 | 336 | | Name | Type | Optional | Description | 337 | | -------------- | ------- | -------- | ----------------------------------------------- | 338 | | application_status | string | n | "approved" or "declined". | 339 | 340 | #### Response 341 | 342 | | Name | Type | Optional | Description | 343 | | ------------ | ------------- | ------------ | ------------- | 344 | | dna | string | n | Group member DNA. | 345 | 346 | #### Example 347 | 348 | ```bash 349 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 350 | 351 | {"result_code":0,"data":{"dna":"", ...}} 352 | 353 | ``` 354 | 355 | 356 | ### 8. Quit group or kick member out 357 | 358 | [DELETE] /groups/{group_id}/members/{group_member_id} 359 | 360 | This API can be used for both quiting group and kicking member out of the group. Use members account to generate 361 | the signature and leave `creator` empty to quit the group and fill in the group owner's info in the `creator` field 362 | to kick member out. 363 | 364 | #### Request 365 | 366 | | Name | Type | Optional | Description | 367 | | -------------- | ------- | -------- | ---------------------------------------- | 368 | | version | string | n | DTCP version. Fixed to "1.0". | 369 | | type | string | n | Fixed to "relation". | 370 | | tag | string | n | Fixed to "group_member". | 371 | | parent_dna | string | n | Latest group member DNA. | 372 | | status | string | n | "deleted". | 373 | | updated | integer | n | Member quiting time. Unix timestamp. | 374 | | creator | object | n | Creator. | 375 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 376 | 377 | `creator` object: 378 | 379 | | Name | Type | Optional | Description | 380 | | -------------- | ------- | -------- | ---------------------------------------- | 381 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 382 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 383 | 384 | #### Response 385 | 386 | | Name | Type | Optional | Description | 387 | | ------------ | ------------- | ------------ | ------------- | 388 | | dna | string | n | Group member DNA. | 389 | 390 | #### Example 391 | 392 | ```bash 393 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 394 | 395 | {"result_code":0,"data":{"dna":"", ...}} 396 | 397 | ``` 398 | 399 | 400 | ### 9. Get group member whitelist 401 | 402 | [GET] /groups/{group_id}/whitelist/members 403 | 404 | #### Query parameters 405 | 406 | | Name | Type | Optional | Description | 407 | | ------------------ | -------- | -------- | --------------------------------------------------- | 408 | | page | integer | y | Page number. Starts from 0. | 409 | | page_size | integer | y | Page size. Default to 20. | 410 | | application_status | string | y | Status filter. "pending", "approved" or "declined". | 411 | 412 | #### Response 413 | 414 | | Name | Type | Optional | Description | 415 | | -------------- | ------- | -------- | ---------------------------------------- | 416 | | id | string | n | Whitelist id. | 417 | | src_id | string | n | Account id. | 418 | | dest_id | string | n | Group id. | 419 | | creator | object | n | Creator. | 420 | | created | integer | n | Whitelist creating time. Unix timestamp. | 421 | | status | string | n | Fixed to "created". | 422 | | extra | object | n | Extra metadata. | 423 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 424 | | dna | string | n | Latest whitelist DNA. | 425 | | account | object | n | Account metadata. | 426 | 427 | `creator` object: 428 | 429 | | Name | Type | Optional | Description | 430 | | -------------- | ------- | -------- | ---------------------------------------- | 431 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 432 | | account_name | string | n | Account name. | 433 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 434 | | sub_account_name | string | y | Sub account name. For fast creation of new sub accounts. | 435 | 436 | `extra` object: 437 | 438 | | Name | Type | Optional | Description | 439 | | -------------- | ------- | -------- | ----------------------------------------------- | 440 | | application_status | string | n | Fixed to "pending". | 441 | 442 | `account` object contains metadata for [account](./account.md#1-get-account-metadata). 443 | 444 | #### Example 445 | 446 | ```bash 447 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 448 | 449 | {"result_code":0,"data":{"dna":"", ...}} 450 | 451 | ``` 452 | 453 | 454 | ### 10. Add group member whitelist 455 | 456 | [POST] /groups/{group_id}/whitelist/members 457 | 458 | #### Request 459 | 460 | | Name | Type | Optional | Description | 461 | | -------------- | ------- | -------- | ---------------------------------------- | 462 | | version | string | n | DTCP version. Fixed to "1.0". | 463 | | type | string | n | Fixed to "relation". | 464 | | tag | string | n | Fixed to "group_member_whitelist". | 465 | | src_id | string | n | Account id. | 466 | | dest_id | string | n | Group id. | 467 | | creator | object | n | Creator. | 468 | | created | integer | n | Whitelist creating time. Unix timestamp. | 469 | | status | string | n | Fixed to "created". | 470 | | extra | object | n | Extra metadata. | 471 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 472 | 473 | `creator` object: 474 | 475 | | Name | Type | Optional | Description | 476 | | -------------- | ------- | -------- | ---------------------------------------- | 477 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 478 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 479 | | sub_account_name | string | y | Sub account name. For fast creation of new sub accounts. | 480 | 481 | `extra` object: 482 | 483 | | Name | Type | Optional | Description | 484 | | -------------- | ------- | -------- | ----------------------------------------------- | 485 | | application_status | string | n | Fixed to "pending". | 486 | 487 | #### Response 488 | 489 | | Name | Type | Optional | Description | 490 | | ------------ | ------------- | ------------ | ------------- | 491 | | id | string | n | Group member whitelist id. | 492 | | dna | string | n | Group member whitelist DNA. | 493 | 494 | #### Example 495 | 496 | ```bash 497 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 498 | 499 | {"result_code":0,"data":{"dna":"", ...}} 500 | 501 | ``` 502 | 503 | 504 | ### 11. Approve or decline group member whitelist 505 | 506 | [PUT] /groups/{group_id}/whitelist/members/{whitelist_id} 507 | 508 | #### Request 509 | 510 | | Name | Type | Optional | Description | 511 | | -------------- | ------- | -------- | ---------------------------------------- | 512 | | version | string | n | DTCP version. Fixed to "1.0". | 513 | | type | string | n | Fixed to "relation". | 514 | | tag | string | n | Fixed to "group_member_whitelist". | 515 | | parent_dna | string | n | Latest whitelist DNA. | 516 | | status | string | n | Fixed to "updated". | 517 | | updated | integer | n | Whitelist updating time. Unix timestamp. | 518 | | creator | object | n | Creator. | 519 | | extra | object | n | Extra metadata. | 520 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 521 | 522 | `creator` object: 523 | 524 | | Name | Type | Optional | Description | 525 | | -------------- | ------- | -------- | ---------------------------------------- | 526 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 527 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 528 | 529 | `extra` object: 530 | 531 | | Name | Type | Optional | Description | 532 | | -------------- | ------- | -------- | ----------------------------------------------- | 533 | | application_status | string | n | "approved" or "declined". | 534 | 535 | #### Response 536 | 537 | | Name | Type | Optional | Description | 538 | | ------------ | ------------- | ------------ | ------------- | 539 | | dna | string | n | Group member whitelist DNA. | 540 | 541 | #### Example 542 | 543 | ```bash 544 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 545 | 546 | {"result_code":0,"data":{"dna":"", ...}} 547 | 548 | ``` 549 | 550 | 551 | ### 12. Quit group member whitelist 552 | 553 | [DELETE] /groups/{group_id}/whitelist/members/{whitelist_id} 554 | 555 | #### Request 556 | 557 | | Name | Type | Optional | Description | 558 | | -------------- | ------- | -------- | ---------------------------------------- | 559 | | version | string | n | DTCP version. Fixed to "1.0". | 560 | | type | string | n | Fixed to "relation". | 561 | | tag | string | n | Fixed to "group_member_whitelist". | 562 | | parent_dna | string | n | Latest whitelist DNA. | 563 | | status | string | n | Fixed to "deleted". | 564 | | updated | integer | n | Whitelist updating time. Unix timestamp. | 565 | | creator | object | n | Creator. | 566 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 567 | 568 | `creator` object: 569 | 570 | | Name | Type | Optional | Description | 571 | | -------------- | ------- | -------- | ---------------------------------------- | 572 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 573 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 574 | 575 | #### Response 576 | 577 | | Name | Type | Optional | Description | 578 | | ------------ | ------------- | ------------ | ------------- | 579 | | dna | string | n | Group member whitelist DNA. | 580 | 581 | #### Example 582 | 583 | ```bash 584 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 585 | 586 | {"result_code":0,"data":{"dna":"", ...}} 587 | 588 | ``` 589 | 590 | 591 | ### 13. Get group shares 592 | 593 | [GET] /groups/{group_id}/shares 594 | 595 | #### Query parameters 596 | 597 | | Name | Type | Optional | Description | 598 | | ------------------ | -------- | -------- | --------------------------------------------------- | 599 | | page | integer | y | Page number. Starts from 0. | 600 | | page_size | integer | y | Page size. Default to 20. | 601 | | application_status | string | y | Status filter. "pending", "approved" or "declined". | 602 | 603 | #### Response 604 | 605 | `data` is an array of [shares](./content-interaction.md#1-get-share-metadata). 606 | 607 | #### Example 608 | 609 | ```bash 610 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 611 | 612 | {"result_code":0,"data":{"dna":"", ...}} 613 | 614 | ``` 615 | 616 | 617 | ### 14. Share to a group 618 | 619 | [POST] /groups/{group_id}/shares 620 | 621 | #### Request 622 | 623 | | Name | Type | Optional | Description | 624 | | -------------- | ------- | -------- | ---------------------------------------- | 625 | | version | string | n | DTCP version. Fixed to "1.0". | 626 | | type | string | n | Fixed to "relation". | 627 | | tag | string | n | Fixed to "group_share". | 628 | | src_id | string | n | Content id. | 629 | | dest_id | string | n | Group id. | 630 | | hp | integer | n | hp value. Greater than or equal to zero. | 631 | | creator | object | n | Creator. | 632 | | created | integer | n | Share created time. Unix timestamp. | 633 | | status | string | n | Fixed to "created". | 634 | | extra | object | y | Extra metadata. | 635 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 636 | 637 | `creator` object: 638 | 639 | | Name | Type | Optional | Description | 640 | | -------------- | ------- | -------- | ---------------------------------------- | 641 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 642 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 643 | | sub_account_name | string | y | Sub account name. For fast creation of new sub accounts. | 644 | 645 | `extra` object: 646 | 647 | | Name | Type | Optional | Description | 648 | | ------------------ | ------- | -------- | ------------------------------------------------ | 649 | | share_id | string | y | Parent share id. | 650 | | application_status | string | y | For group requiring application. Fill "pending". | 651 | | application_expire | integer | y | Application expiration time. | 652 | 653 | #### Response 654 | 655 | | Name | Type | Optional | Description | 656 | | ------- | ------- | -------- | ------------- | 657 | | id | string | n | Share id. | 658 | | dna | string | n | Share DNA. | 659 | 660 | #### Example 661 | 662 | ```bash 663 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 664 | 665 | {"result_code":0,"data":{"dna":"", ...}} 666 | 667 | ``` 668 | 669 | 670 | ### 15. Approve or decline share application 671 | 672 | [PUT] /shares/{share_id} 673 | 674 | #### Request 675 | 676 | | Name | Type | Optional | Description | 677 | | -------------- | ------- | -------- | ---------------------------------------- | 678 | | version | string | n | DTCP version. Fixed to "1.0". | 679 | | type | string | n | Fixed to "relation". | 680 | | tag | string | n | Fixed to "group_share". | 681 | | parent_dna | string | n | Latest share DNA. | 682 | | status | string | n | Fixed to "updated". | 683 | | updated | integer | n | Share updated time. Unix timestamp. | 684 | | creator | object | n | Creator. Group owner | 685 | | extra | object | n | Extra metadata. | 686 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 687 | 688 | `creator` object: 689 | 690 | | Name | Type | Optional | Description | 691 | | -------------- | ------- | -------- | ---------------------------------------- | 692 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 693 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 694 | 695 | `extra` object: 696 | 697 | | Name | Type | Optional | Description | 698 | | ------------------ | ------- | -------- | ------------------------------------------------ | 699 | | application_status | string | n | "approved" or "declined". | 700 | 701 | #### Response 702 | 703 | | Name | Type | Optional | Description | 704 | | ------- | ------- | -------- | ----------- | 705 | | dna | string | n | Share DNA. | 706 | 707 | #### Example 708 | 709 | ```bash 710 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 711 | 712 | {"result_code":0,"data":{"dna":"", ...}} 713 | 714 | ``` 715 | 716 | 717 | ### 16. Delete group share 718 | 719 | [DELETE] /shares/{share_id} 720 | 721 | This API can be called both by group owner or share creator with corresponding creator info and its signature. 722 | 723 | #### Request 724 | 725 | | Name | Type | Optional | Description | 726 | | -------------- | ------- | -------- | ---------------------------------------- | 727 | | version | string | n | DTCP version. Fixed to "1.0". | 728 | | type | string | n | Fixed to "relation". | 729 | | tag | string | n | Fixed to "group_share". | 730 | | parent_dna | string | n | Latest share DNA. | 731 | | status | string | n | Fixed to "deleted". | 732 | | updated | integer | n | Share updated time. Unix timestamp. | 733 | | creator | object | y | Creator. Group owner. | 734 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 735 | 736 | `creator` object: 737 | 738 | | Name | Type | Optional | Description | 739 | | -------------- | ------- | -------- | ---------------------------------------- | 740 | | account_id | string | n | Account id. Root account id in the case of Sub account posting. | 741 | | sub_account_id | string | y | Sub account id. Refer to [Sub account](./dtcp.md#sub-accounts) for details. | 742 | 743 | #### Response 744 | 745 | | Name | Type | Optional | Description | 746 | | ------------ | ------------- | ------------ | ------------- | 747 | | dna | string | n | Share DNA. | 748 | 749 | #### Example 750 | 751 | ```bash 752 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 753 | 754 | {"result_code":0,"data":{"dna":"", ...}} 755 | 756 | ``` 757 | 758 | 759 | ### 17. Get group avatar metadata 760 | 761 | [GET] /groups/{group_id}/avatar 762 | 763 | #### Response 764 | 765 | `data` is [content](./content.md#1-get-content-metadata) metadata. 766 | 767 | #### Example 768 | 769 | ```bash 770 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 771 | 772 | {"result_code":0,"data":{"dna":"", ...}} 773 | 774 | ``` 775 | 776 | 777 | ### 18. Get group avatar raw image 778 | 779 | [GET] /groups/{group_id}/avatar/raw 780 | 781 | Primas Node can build local cache of raw image for accessing speed. Or redirect the request to 782 | image URI for raw content directly. 783 | 784 | #### Response 785 | 786 | Response is raw image data. 787 | 788 | #### Example 789 | 790 | ```bash 791 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 792 | 793 | {"result_code":0,"data":{"dna":"", ...}} 794 | 795 | ``` 796 | -------------------------------------------------------------------------------- /node.md: -------------------------------------------------------------------------------- 1 | # Primas Node API Documentation 2 | 3 | ## Node APIs 4 | 5 | ### 1. Get node list 6 | 7 | [GET] /nodes 8 | 9 | #### Query parameters 10 | 11 | | Name | Type | Optional | Description | 12 | | ------------------ | -------- | -------- | --------------------------------------------------- | 13 | | page | integer | y | Page number. Starts from 0. | 14 | | page_size | integer | y | Page size. Default to 20. | 15 | 16 | #### Response 17 | 18 | `data` is an array of nodes: 19 | 20 | | Name | Type | Optional | Description | 21 | | -------------- | ------- | -------- | ---------------------------------------- | 22 | | id | string | n | Node id.| 23 | | title | string | n | Node name. | 24 | | created | integer | n | Node creation time. Unix timestamp. | 25 | | updated | integer | n | Node last updating time. Unix timestamp. | 26 | | url | string | n | Node access url. | 27 | | withdrawal_fee | big integer | n | Withdrawal fee charged by node. | 28 | | address_hot | string | n | Node hot address. | 29 | | address_cold | string | n | Node cold address. | 30 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 31 | | transaction_id | string | n | Latest transaction id. | 32 | 33 | #### Example 34 | 35 | ```bash 36 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 37 | 38 | {"result_code":0,"data":{"dna":"", ...}} 39 | 40 | ``` -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "primas-api-doc", 3 | "version": "1.0.0", 4 | "description": "Primas Node API Documentation", 5 | "main": "README.md", 6 | "scripts": { 7 | "test": "echo \"Error: no test specified\" && exit 1", 8 | "build": "node run toc.js" 9 | }, 10 | "repository": { 11 | "type": "git", 12 | "url": "git+https://github.com/primasio/primas-api-doc.git" 13 | }, 14 | "author": "Gan Lu", 15 | "license": "Apache-2.0", 16 | "bugs": { 17 | "url": "https://github.com/primasio/primas-api-doc/issues" 18 | }, 19 | "homepage": "https://github.com/primasio/primas-api-doc#readme", 20 | "dependencies": { 21 | "markdown-toc": "^1.2.0" 22 | } 23 | } 24 | -------------------------------------------------------------------------------- /query.md: -------------------------------------------------------------------------------- 1 | # Primas Node API Documentation 2 | 3 | ## Query APIs 4 | 5 | ### 1. Query all 6 | 7 | [GET] /query 8 | 9 | #### Query parameters 10 | 11 | | Name | Type | Optional | Description | 12 | | ------------------ | -------- | -------- | -------------------------------------------------------------------- | 13 | | page | integer | y | Page number. Starts from 0. | 14 | | page_size | integer | y | Page size. Default to 20. | 15 | | text | string | y | Text filter. Full text search on title, description, etc. | 16 | | type | string | y | Query type. Currently supports "all", "share", "account", "group". | 17 | | category | string | y | Category filter. | 18 | 19 | #### Response 20 | 21 | `data` is an array containing [groups](./group.md#1-get-group-metadata), 22 | [content](./content.md#1-get-content-metadata), [accounts](./account.md#1-get-account-metadata) 23 | or a mixture of all types. 24 | 25 | #### Example 26 | 27 | ```bash 28 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 29 | 30 | {"result_code":0,"data":{"dna":"", ...}} 31 | 32 | ``` 33 | ### 2. Find content using URL or hash 34 | 35 | [GET] /query/content 36 | 37 | #### Query parameters 38 | 39 | | Name | Type | Optional | Description | 40 | | ------------------ | -------- | -------- | -------------------------------------------------------------------- | 41 | | url | string | y | Url encoded url. | 42 | | hash | string | y | Lowercase hex string of the Keccak256 hash of the raw content. | 43 | 44 | #### Response 45 | 46 | `data` is an array of [content](./content.md#1-get-content-metadata). 47 | 48 | #### Example 49 | 50 | ```bash 51 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 52 | 53 | {"result_code":0,"data":{"dna":"", ...}} 54 | 55 | ``` 56 | 57 | 58 | ### 3. Find reproductions using URL(designing) 59 | 60 | [GET] /query/reproductions 61 | 62 | #### Query parameters 63 | 64 | | Name | Type | Optional | Description | 65 | | ------------------ | -------- | -------- | -------------------------------------------------------------------- | 66 | | page | integer | y | Page number. Starts from 0. | 67 | | page_size | integer | y | Page size. Default to 20. | 68 | | url | string | n | Url encoded url. | 69 | 70 | #### Response 71 | 72 | `data` is an array of reproductions: 73 | 74 | 75 | 76 | #### Example 77 | 78 | ```bash 79 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 80 | 81 | {"result_code":0,"data":{"dna":"", ...}} 82 | 83 | ``` -------------------------------------------------------------------------------- /system.md: -------------------------------------------------------------------------------- 1 | # Primas Node API Documentation 2 | 3 | ## System APIs 4 | 5 | ### 1. Get system parameters 6 | 7 | [GET] /system 8 | 9 | #### Response 10 | 11 | | Name | Type | Optional | Description | 12 | | ------------------------ | ----------- | -------- | ---------------------------------------- | 13 | | lock_amount_content | big integer | n | Token lock amount for posting content. | 14 | | lock_period_content | integer | n | Token lock period in seconds for posting content. | 15 | | lock_amount_group_join | big integer | n | Token lock amount for joining group. | 16 | | lock_amount_group_create | big integer | n | Token lock amount for creating group.| 17 | | consume_amount_report | big integer | n | Token consumed amount for report share. | 18 | 19 | #### Example 20 | 21 | ```bash 22 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 23 | 24 | {"result_code":0,"data":{"dna":"", ...}} 25 | 26 | ``` 27 | -------------------------------------------------------------------------------- /timeline.md: -------------------------------------------------------------------------------- 1 | # Primas Node API Documentation 2 | 3 | ## Timeline APIs 4 | 5 | ### 1. Get account timeline 6 | 7 | [GET] /accounts/{account_id}/timeline 8 | 9 | Get all the shares in all the groups account has joined. 10 | Notice that **if the same article is shared multiple times 11 | in several adjacent shares, only the first one will show.** 12 | 13 | #### Query parameters 14 | 15 | | Name | Type | Optional | Description | 16 | | ------------------ | -------- | -------- | --------------------------------------------------- | 17 | | page | integer | y | Page number. Starts from 0. | 18 | | page_size | integer | y | Page size. Default to 20. | 19 | 20 | #### Response 21 | 22 | `data` is an array of [shares](./content-interaction.md#1-get-share-metadata): 23 | 24 | #### Example 25 | 26 | ```bash 27 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 28 | 29 | {"result_code":0,"data":{"dna":"", ...}} 30 | 31 | ``` 32 | -------------------------------------------------------------------------------- /toc.js: -------------------------------------------------------------------------------- 1 | var toc = require('markdown-toc'); 2 | var fs = require('fs'); 3 | 4 | var mdFiles = [ 5 | "content.md", 6 | "content-interaction.md", 7 | "group.md", 8 | "account.md", 9 | "token.md", 10 | "timeline.md", 11 | "query.md", 12 | "system.md", 13 | "node.md", 14 | "transaction.md" 15 | ]; 16 | 17 | var tocContent = ""; 18 | 19 | function processAt(idx) { 20 | 21 | if (idx >= mdFiles.length) 22 | { 23 | finished(); 24 | return; 25 | } 26 | 27 | fs.readFile(mdFiles[idx], 'utf8', function(err, data) { 28 | tocContent += toc(data, { 29 | firsth1: false, 30 | maxdepth: 2 31 | }).content + "\n"; 32 | processAt(idx + 1); 33 | }); 34 | } 35 | 36 | function finished() { 37 | console.log(tocContent); 38 | } 39 | 40 | processAt(0); 41 | -------------------------------------------------------------------------------- /token.md: -------------------------------------------------------------------------------- 1 | # Primas Node API Documentation 2 | 3 | ## Token APIs 4 | 5 | 6 | ### 1. Get account tokens data 7 | 8 | [GET] /accounts/{account_id}/tokens 9 | 10 | #### Response 11 | 12 | | Name | Type | Optional | Description | 13 | | -------------------- | ----------- | -------- | ------------------------------------- | 14 | | balance | big integer | n | Token balance. | 15 | | pre_lock_all | big integer | n | Total pre-locked amount. | 16 | | pre_lock_available | big integer | n | Remaining pre-locked amount. | 17 | | incentives_all | big integer | n | Total incentives on this node. . | 18 | | incentives_locked | big integer | n | Incentives locked on this node. | 19 | | incentives_on_node | big integer | n | Amount in the node's incentives pool. | 20 | 21 | #### Example 22 | 23 | ```bash 24 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 25 | 26 | {"result_code":0,"data":{"dna":"", ...}} 27 | 28 | ``` 29 | 30 | 31 | ### 2. Get incentives list 32 | 33 | [GET] /accounts/{account_id}/tokens/incentives 34 | 35 | #### Query parameters 36 | 37 | | Name | Type | Optional | Description | 38 | | ----------- | -------- | -------- | --------------------------------- | 39 | | start_date | integer | y | Query start date. Unix timestamp. | 40 | | end_date | integer | y | Query end date. Unix timestamp. | 41 | | page | integer | y | Page number. Starts from 0. | 42 | | page_size | integer | y | Page size. Default to 20. | 43 | 44 | #### Response 45 | 46 | Response `data` is an array whose element containing: 47 | 48 | | Name | Type | Optional | Description | 49 | | ----------------- | ------------- | -------- | ----------------------------------------------------------------- | 50 | | date | string | n | Incentives date. Unix timestamp. | 51 | | from | string | n | "original", "share", "group", "original_like", "original_comment", "original_share". | 52 | | object_id | string | n | Corresponding object id. Such as article_id, group_id, share_id. | 53 | | amount | big integer | n | Incentives amount. | 54 | 55 | #### Example 56 | 57 | ```bash 58 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 59 | 60 | {"result_code":0,"data":{"dna":"", ...}} 61 | 62 | ``` 63 | 64 | 65 | ### 3. Get incentives statistics list 66 | 67 | [GET] /accounts/{account_id}/tokens/incentives/stats 68 | 69 | #### Query parameters 70 | 71 | | Name | Type | Optional | Description | 72 | | ----------- | -------- | -------- | --------------------------------- | 73 | | start_date | integer | y | Query start date. Unix timestamp. | 74 | | end_date | integer | y | Query end date. Unix timestamp. | 75 | | page | integer | y | Page number. Starts from 0. | 76 | | page_size | integer | y | Page size. Default to 20. | 77 | 78 | #### Response 79 | 80 | Response `data` is an array whose element containing: 81 | 82 | | Name | Type | Optional | Description | 83 | | ----------------- | ------------- | -------- | ------------------------------------- | 84 | | date | string | n | Incentives date. Unix timestamp. | 85 | | total | big integer | n | Total incentives get for today. | 86 | | originals | big integer | n | Incentives get from original. 40% of all the incentives. | 87 | | shares | big integer | n | Incentives get from shares. 40% of all the incentives. | 88 | | original_likes | big integer | n | Incentives get from likes. 10% of the original incentives. | 89 | | original_comments | big integer | n | Incentives get from comments. 10% of the original incentives. | 90 | | original_shares | big integer | n | Incentives get from shares. 10% of the original incentives. | 91 | | groups | big integer | n | Incentives get from group management. | 92 | 93 | #### Example 94 | 95 | ```bash 96 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 97 | 98 | {"result_code":0,"data":{"dna":"", ...}} 99 | 100 | ``` 101 | 102 | 103 | ### 4. Get incentives withdrawal list 104 | 105 | [GET] /accounts/{account_id}/tokens/incentives/withdrawal 106 | 107 | #### Query parameters 108 | 109 | | Name | Type | Optional | Description | 110 | | ----------- | -------- | -------- | ----------------------------------- | 111 | | start_date | integer | y | Query start date. Unix timestamp. | 112 | | end_date | integer | y | Query end date. Unix timestamp. | 113 | | page | integer | y | Page number. Starts from 0. | 114 | | page_size | integer | y | Page size. Default to 20. | 115 | | status | string | y | Status filter. "pending" or "done". | 116 | 117 | #### Response 118 | 119 | Response `data` is an array whose element containing: 120 | 121 | | Name | Type | Optional | Description | 122 | | -------------- | ----------- | -------- | ------------------------------------------------------------- | 123 | | id | string | n | Withdrawal id. | 124 | | created | integer | n | Withdrawal created time. Unix timestamp. | 125 | | updated | integer | n | Withdrawal updated time. | 126 | | amount | big integer | n | Withdrawal amount. | 127 | | node_fee | big integer | n | Node charged withdrawal fee. | 128 | | status | string | n | Withdrawal status. "pending", "done" or "cancelled". | 129 | | transaction | object | n | Withdrawal [transaction object](./transaction.md#transaction) | 130 | 131 | #### Example 132 | 133 | ```bash 134 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 135 | 136 | {"result_code":0,"data":{"dna":"", ...}} 137 | 138 | ``` 139 | 140 | 141 | ### 5. Withdraw incentives 142 | 143 | [POST] /accounts/{account_id}/tokens/incentives/withdrawal 144 | 145 | #### Request 146 | 147 | | Name | Type | Optional | Description | 148 | | ------------ | ----------- | ------------ | ---------------------------------------------------------- | 149 | | node_id | string | n | Node id. 150 | | created | integer | n | Withdrawal creation time. Unix timestamp. | 151 | | amount | big integer | n | Withdraw amount value. | 152 | | node_fee | big integer | n | Node charged withdrawal fee. | 153 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 154 | 155 | #### Response 156 | 157 | | Name | Type | Optional | Description | 158 | | ---- | ------ | -------- | --------------- | 159 | | id | string | n | Withdrawal id. | 160 | 161 | #### Example 162 | 163 | ```bash 164 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 165 | 166 | {"result_code":0,"data":{"dna":"", ...}} 167 | 168 | ``` 169 | 170 | 171 | ### 6. Get token pre-lock list 172 | 173 | [GET] /accounts/{account_id}/tokens/pre_locks 174 | 175 | #### Query parameters 176 | 177 | | Name | Type | Optional | Description | 178 | | ----------- | -------- | -------- | ----------------------------------- | 179 | | start_date | integer | y | Query start date. Unix timestamp. | 180 | | end_date | integer | y | Query end date. Unix timestamp. | 181 | | page | integer | y | Page number. Starts from 0. | 182 | | page_size | integer | y | Page size. Default to 20. | 183 | | type | string | y | Type filter. "lock" or "unlock". | 184 | 185 | #### Response 186 | 187 | Response `data` is an array whose element containing: 188 | 189 | | Name | Type | Optional | Description | 190 | | ------------------ | ----------- | -------- | ---------------------------------------- | 191 | | id | string | n | Lock id. | 192 | | created | integer | n | Lock creation time. Unix timestamp. | 193 | | type | string | n | Pre-lock type. "lock" or "unlock" | 194 | | amount | big integer | n | Pre-lock amount. | 195 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 196 | | transaction_hash | string | n | Transaction hash. | 197 | | transaction_status | string | n | Transaction status. "pending", "done" or "failed" | 198 | 199 | #### Example 200 | 201 | ```bash 202 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 203 | 204 | {"result_code":0,"data":{"dna":"", ...}} 205 | 206 | ``` 207 | 208 | 209 | ### 7. Pre-lock tokens 210 | 211 | [POST] /accounts/{account_id}/tokens/pre_locks 212 | 213 | #### Request 214 | 215 | | Name | Type | Optional | Description | 216 | | ---------------- | ------- | -------- | -------------------------------------- | 217 | | transaction | string | n | Signed raw transaction to lock tokens. | 218 | 219 | #### Response 220 | 221 | | Name | Type | Optional | Description | 222 | | ------- | ------ | -------- | ------------ | 223 | | id | string | n | Pre-lock id. | 224 | 225 | #### Example 226 | 227 | ```bash 228 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 229 | 230 | {"result_code":0,"data":{"dna":"", ...}} 231 | 232 | ``` 233 | 234 | 235 | ### 8. Unlock pre-locked tokens(designing) 236 | 237 | [DELETE] /accounts/{account_id}/tokens/pre_locks 238 | 239 | #### Request 240 | 241 | | Name | Type | Optional | Description | 242 | | ------------ | ----------- | -------- | ---------------------------------------------------------- | 243 | | node_id | string | n | Primas Node id. | 244 | | created | integer | n | People creation time. Unix timestamp. | 245 | | amount | big integer | n | Unlock amount. | 246 | | signature | string | n | [Metadata signature](./dtcp.md#metadata-signature). | 247 | 248 | #### Response 249 | 250 | | Name | Type | Optional | Description | 251 | | ------- | ------ | -------- | ------------ | 252 | | id | string | n | Pre-lock id. | 253 | 254 | #### Example 255 | 256 | ```bash 257 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 258 | 259 | {"result_code":0,"data":{"dna":"", ...}} 260 | 261 | ``` 262 | 263 | 264 | ### 9. Get token lock list 265 | 266 | [GET] /accounts/{account_id}/tokens/locks 267 | 268 | #### Query parameters 269 | 270 | | Name | Type | Optional | Description | 271 | | ----------- | -------- | -------- | ----------------------------------------------- | 272 | | start_date | integer | y | Query start date. Unix timestamp. | 273 | | end_date | integer | y | Query end date. Unix timestamp. | 274 | | page | integer | y | Page number. Starts from 0. | 275 | | page_size | integer | y | Page size. Default to 20. | 276 | | type | string | y | Type filter. "content", "group_create", "group_join" or "report". | 277 | 278 | #### Response 279 | 280 | Response `data` is an array whose element containing: 281 | 282 | | Name | Type | Optional | Description | 283 | | --------- | ----------- | -------- | -------------------------------------------------------- | 284 | | id | string | n | Lock id. | 285 | | amount | big integer | n | Lock amount. | 286 | | expire | integer | n | Lock expire time. Unix timestamp. 0 for non-expire locks. | 287 | | type | string | n | Lock type. "content", "group_create", "group_join" or "report". | 288 | | object_id | string | n | Locked object(content, group, report) id. | 289 | | created | integer | n | Lock creation time. Unix timestamp. | 290 | 291 | #### Example 292 | 293 | ```bash 294 | $ curl -x https://rigel-a.primas.network/v3/content -d '{"type":"article","content":"...","signature":"..."}' 295 | 296 | {"result_code":0,"data":{"dna":"", ...}} 297 | 298 | ``` 299 | -------------------------------------------------------------------------------- /transaction.md: -------------------------------------------------------------------------------- 1 | `transaction` object: 2 | 3 | | Name | Type | Optional | Description | 4 | | ------------------- | ----------- | -------- | ------------------------------------------------------------- | 5 | | transaction_id | string | y | Transaction hash. | 6 | | block_number | integer | y | Block number of this transaction. | 7 | | block_confirmations | integer | y | Block confirmation time. | 8 | | estimated_time | integer | n | Estimated confirmation time. Unix timestamp. | 9 | | confirmed_time | integer | y | Confirmation time. Unix timestamp. | 10 | --------------------------------------------------------------------------------