github.com/decred/politeia@v1.4.0/politeiawww/api/records/v1/api.md (about)

     1  # Records API Specification
     2  
     3  This document describes the records plugin API.
     4  
     5  **Routes**
     6  
     7  - [`Policy`](#policy)
     8  - [`New`](#new)
     9  - [`Edit`](#edit)
    10  - [`SetStatus`](#set-status)
    11  - [`Details`](#details)
    12  - [`Timestamps`](#timestamps)
    13  - [`Records`](#records)
    14  - [`Inventory`](#inventory)
    15  - [`InventoryOrdered`](#inventory-ordered)
    16  - [`UserRecords`](#user-records)
    17  
    18  **Error Status Codes**
    19  
    20  - [`ErrorCodeInvalid`](#ErrorCodeInvalid)
    21  - [`ErrorCodeInputInvalid`](#ErrorCodeInputInvalid)
    22  - [`ErrorCodeFilesEmpty`](#ErrorCodeFilesEmpty)
    23  - [`ErrorCodeFileNameInvalid`](#ErrorCodeFileNameInvalid)
    24  - [`ErrorCodeFileNameDuplicate`](#ErrorCodeFileNameDuplicate)
    25  - [`ErrorCodeFileMIMETypeInvalid`](#ErrorCodeFileMIMETypeInvalid)
    26  - [`ErrorCodeFileMIMETypeUnsupported`](#ErrorCodeFileMIMETypeUnsupported)
    27  - [`ErrorCodeFileDigestInvalid`](#ErrorCodeFileDigestInvalid)
    28  - [`ErrorCodeFilePayloadInvalid`](#ErrorCodeFilePayloadInvalid)
    29  - [`ErrorCodeMetadataStreamIDInvalid`](#ErrorCodeMetadataStreamIDInvalid)
    30  - [`ErrorCodePublicKeyInvalid`](#ErrorCodePublicKeyInvalid)
    31  - [`ErrorCodeSignatureInvalid`](#ErrorCodeSignatureInvalid)
    32  - [`ErrorCodeRecordTokenInvalid`](#ErrorCodeRecordTokenInvalid)
    33  - [`ErrorCodeRecordNotFound`](#ErrorCodeRecordNotFound)
    34  - [`ErrorCodeRecordLocked`](#ErrorCodeRecordLocked)
    35  - [`ErrorCodeNoRecordChanges`](#ErrorCodeNoRecordChanges)
    36  - [`ErrorCodeRecordStateInvalid`](#ErrorCodeRecordStateInvalid)
    37  - [`ErrorCodeRecordStatusInvalid`](#ErrorCodeRecordStatusInvalid)
    38  - [`ErrorCodeStatusChangeInvalid`](#ErrorCodeStatusChangeInvalid)
    39  - [`ErrorCodeStatusReasonNotFound`](#ErrorCodeStatusReasonNotFound)
    40  - [`ErrorCodePageSizeExceeded`](#ErrorCodePageSizeExceeded)
    41  
    42  ## HTTP status codes and errors
    43  
    44  All routes, unless otherwise specified, shall return `200 OK` when successful,
    45  `400 Bad Request` when an error has occurred due to user input, or `500
    46  Internal Server Error` when an unexpected server error has occurred. The format
    47  of errors is as follows:
    48  
    49  **`4xx` errors**
    50  
    51  | Field | Type | Description |
    52  |-|-|-|
    53  | errorcode | number | One of the [error codes](#error-codes) |
    54  | errorcontext | String | This field is used to provide additional information for certain errors. |
    55  
    56  **`5xx` errors**
    57  
    58  | Field | Type | Description |
    59  |-|-|-|
    60  | errorcode | number | An error code that can be used to track down the internal server error that occurred; it should be reported to Politeia administrators. |
    61  
    62  ## Routes
    63  
    64  ### `Policy` 
    65  
    66  Retrieve the policy settings for the records API.
    67  
    68  **Route**: `POST /policy`
    69  
    70  **Params**: none
    71  
    72  **Reply**:
    73  
    74  | Field | Type | Description |
    75  |-|-|-|
    76  | recordspagesize | number | Maximum number of records that can be requested in a /records request. |
    77  | inventorypagesize | number | Number of tokens that will be returned per page for all /inventory requests. |
    78  
    79  ### `New`
    80  
    81  Submit a new record.
    82  
    83  **Route**: `POST /new`
    84  
    85  **Params**:
    86  
    87  | Parameter | Type | Description | Required |
    88  |-|-|-|-|
    89  | files | [][`File`](#file) | Record files. | Yes |
    90  | publickey | string | Signing user public key. | Yes |
    91  | signature | string | Client signature of the record merkle root. The merkle root is the ordered merkle root of all record Files. | Yes |
    92  
    93  **Reply**:
    94  
    95  | Field | Type | Description |
    96  |-|-|-|
    97  | record | [`Record`](#record) | Submitted record. |
    98  
    99  ### `Edit`
   100  
   101  Edit an existing record.
   102  
   103  **Route**: `POST /edit`
   104  
   105  **Params**:
   106  
   107  | Parameter | Type | Description | Required |
   108  |-|-|-|-|
   109  | token | string | Existing record token. | Yes |
   110  | files | [][`File`](#file) | Record files. | Yes |
   111  | publickey | string | Signing user public key. | Yes |
   112  | signature | string | Client signature of the record merkle root. The merkle root is the ordered merkle root of all record Files. | Yes |
   113  
   114  **Reply**:
   115  
   116  | Field | Type | Description |
   117  |-|-|-|
   118  | record | [`Record`](#record) | Submitted record. |
   119  
   120  ### `Set Status`
   121  
   122  Set the status of a record. Some status changes require a reason to be included.
   123  
   124  **Route**: `POST /setstatus`
   125  
   126  **Params**:
   127  
   128  | Parameter | Type | Description | Required |
   129  |-|-|-|-|
   130  | token | string | Record token. | Yes |
   131  | version | number | Record version. | Yes |
   132  | status | [`RecordStatusT`](#record-statuses) | Record's new status. | Yes |
   133  | reason | string | Status change reason. | Required for some statuses |
   134  | publickey | string | Signing user public key. | Yes |
   135  | signature | string | Client signature of the Token+Version+Status+Reason. | Yes |
   136  
   137  **Reply**:
   138  
   139  | Field | Type | Description |
   140  |-|-|-|
   141  | record | [`Record`](#record) | Record after status change. |
   142  
   143  ### `Details`
   144  
   145  Retrieve the details of a record. The full record will be returned.
   146  If no version is specified then the most recent version will be returned.
   147  
   148  **Route**: `POST /details`
   149  
   150  **Params**:
   151  
   152  | Parameter | Type | Description | Required |
   153  |-|-|-|-|
   154  | token | string | Record token. | Yes |
   155  | version | number | Record version. | Yes |
   156  
   157  **Reply**:
   158  
   159  | Field | Type | Description |
   160  |-|-|-|
   161  | record | [`Record`](#record) | Record after status change. |
   162  
   163  ### `Timestamps`
   164  
   165  Retrieve the timestamps for a specific record version. If the
   166  version is omitted, the timestamps for the most recent version will be
   167  returned.
   168  
   169  **Route**: `POST /timestamps`
   170  
   171  **Params**:
   172  
   173  | Parameter | Type | Description | Required |
   174  |-|-|-|-|
   175  | token | string | Record token. | Yes |
   176  | version | number | Record version. | Yes |
   177  
   178  **Reply**:
   179  
   180  | Field | Type | Description |
   181  |-|-|-|
   182  | recordmetadata | [`Timestamp`](#timestamp) | Record metadata timestamp. |
   183  | metadata | map[string]map[number][`Timestamp`](#timestamp) | Map of metadata streams timestamps. map[pluginID]map[streamID]timestamp. |
   184  | files | map[string][`Timestamp`](#timestamp) | Map of record files timestamps. map[filename]timestamp. |
   185  
   186  ### `Records`
   187  
   188  Retrieve a batch of records. This route should be used when the
   189  client only requires select content from the record. The Details command
   190  should be used when the full record content is required. Unvetted record
   191  files are only returned to admins and the author. Any tokens that did not
   192  correspond to a record will not be included in the reply.
   193  
   194  **Note**: partial record's merkle root is not verifiable - when generating
   195  the record's merkle all files must be present.
   196  
   197  **Route**: `POST /records`
   198  
   199  **Params**:
   200  
   201  | Parameter | Type | Description | Required |
   202  |-|-|-|-|
   203  | requests | [][`RecordRequest`](#record-request) | Select content from a record. | Yes |
   204  
   205  **Reply**:
   206  
   207  | Field | Type | Description |
   208  |-|-|-|
   209  | records | map[string][`Record`](#record) | Map of requested records. |
   210  
   211  ### `Inventory`
   212  
   213  Retrieve the tokens of the records in the inventory, categorized
   214  by record state and record status. The tokens are ordered by the timestamp
   215  of their most recent status change, sorted from newest to oldest.
   216  
   217  The state, status, and page arguments can be provided to request a specific
   218  page of record tokens.
   219  
   220  If no status is provided then a page of tokens for all statuses are
   221  returned. The state and page arguments will be ignored.
   222  
   223  Unvetted record tokens will only be returned to admins.
   224  
   225  **Route**: `POST /inventory`
   226  
   227  **Params**:
   228  
   229  | Parameter | Type | Description | Required |
   230  |-|-|-|-|
   231  | state | [`RecordStateT`](#record-states) | Record state. | No |
   232  | status | [`RecordStatusT`](#record-statuses) | Record status. | No |
   233  | page | number | Requested page. | No |
   234  
   235  **Reply**:
   236  
   237  | Field | Type | Description |
   238  |-|-|-|
   239  | unvetted | map[string][]string | Map of unvetted records tokens. |
   240  | vetted | map[string][]string | Map of vetted records tokens. |
   241  
   242  ### `Inventory Ordered`
   243  
   244  Retrieve a page of record tokens ordered by the timestamp
   245  of their most recent status change from newest to oldest. The reply will
   246  include tokens for all record statuses. Unvetted tokens will only be
   247  returned to admins.
   248  
   249  **Params**:
   250  
   251  | Parameter | Type | Description | Required |
   252  |-|-|-|-|
   253  | state | [`RecordStateT`](#record-states) | Record state. | Yes |
   254  | page | number | Requested page. | Yes |
   255  
   256  **Reply**:
   257  
   258  | Field | Type | Description |
   259  |-|-|-|
   260  | tokens | []string | Page of tokens. |
   261  
   262  ### `User Records`
   263  
   264  Retrieve the tokens of all records submitted by a user.
   265  Unvetted record tokens are only returned to admins and the record author.
   266  
   267  **Params**:
   268  
   269  | Parameter | Type | Description | Required |
   270  |-|-|-|-|
   271  | userid | string | User ID. | Yes |
   272  
   273  **Reply**:
   274  
   275  | Field | Type | Description |
   276  |-|-|-|
   277  | unvetted | []string | User's unvetted records. |
   278  | vetted | []string | User's vetted records. |
   279  
   280  ### `Error codes`
   281  
   282  | Error | Value | Description |
   283  |-|-|-|
   284  | ErrorCodeInvalid | 0 | Error invalid. |
   285  | ErrorCodeInputInvalid | 1 | Input invalid. |
   286  | ErrorCodeFilesEmpty | 2 | Files are empty. |
   287  | ErrorCodeFileNameInvalid | 3 | File name invalid. |
   288  | ErrorCodeFileNameDuplicate | 4 | File name duplicate. |
   289  | ErrorCodeFileMIMETypeInvalid | 5 | File MIME type invalid. |
   290  | ErrorCodeFileMIMETypeUnsupported | 6 | File MIME type unsupported. |
   291  | ErrorCodeFileDigestInvalid | 7 | File digest invalid. |
   292  | ErrorCodeFilePayloadInvalid | 8 | File payload invalid. |
   293  | ErrorCodeMetadataStreamIDInvalid | 9 | Metadata stream ID invalid. |
   294  | ErrorCodePublicKeyInvalid | 10 | Public key invalid. |
   295  | ErrorCodeSignatureInvalid | 11 | Signature invalid. |
   296  | ErrorCodeRecordTokenInvalid | 12 | Record token invalid. |
   297  | ErrorCodeRecordNotFound | 14 | Record not found. |
   298  | ErrorCodeRecordLocked | 14 | Record locked. |
   299  | ErrorCodeNoRecordChanges | 15 | No record changes. |
   300  | ErrorCodeRecordStateInvalid | 16 | Record state invalid. |
   301  | ErrorCodeRecordStatusInvalid | 17 | Record status invalid. |
   302  | ErrorCodeStatusChangeInvalid | 18 | Status change invalid. |
   303  | ErrorCodeStatusReasonNotFound | 19 | Status reason not found. |
   304  | ErrorCodePageSizeExceeded | 20 | Page size exceeded. |
   305  
   306  ### `Record`
   307  
   308  Represents a record and all of its content.
   309  
   310  | Field | Type | Description |
   311  |-|-|-|
   312  | state | [`RecordStateT`](#record-states) | Record state. |
   313  | status | [`RecordStatusT`](#record-statuses) | Record status. |
   314  | version | number | Record version. |
   315  | timestamp | number | Last update. |
   316  | username | string | Author username. |
   317  | metadata | [][`MetadataStream`](#metadata-stream) | Metadata streams. |
   318  | files | [][`File`](#file) | User submitted files. |
   319  | censorshiprecord | [`CensorshipRecord`](#censorship-record) | Contains cryptographic proof that a record was accepted for review by the server. The proof is verifiable by the client. |
   320  
   321  ### `Record states`
   322  
   323  | State | Value | Description |
   324  |-|-|-|
   325  | RecordStateInvalid | 0 | Invalid. |
   326  | RecordStateUnvetted | 1 | Unvetted. |
   327  | RecordStateVetted | 2 | Vetted. |
   328  
   329  ### `Record statuses`
   330  
   331  | Status | Value | Description |
   332  |-|-|-|
   333  | RecordStatusInvalid | 0 | Invalid. |
   334  | RecordStatusUnreviewed | 1 | Unreviewed. |
   335  | RecordStatusReviewed | 2 | Reviewed. |
   336  | RecordStatusPublic | 2 | Public. |
   337  | RecordStatusCensored | 3 | Cesnored. |
   338  | RecordStatusArchived | 3 | Archived. |
   339  
   340  ### `Metadata stream`
   341  
   342  Describes a record metadata stream.
   343  
   344  | Field | Type | Description |
   345  |-|-|-|
   346  | pluginid | string | Plugin ID. |
   347  | streamid | number | Stream ID. |
   348  | payload | string | JSON encoded payload. |
   349  
   350  ### `File`
   351  
   352  Describes an individual file that is part of the record.
   353  
   354  | Field | Type | Description |
   355  |-|-|-|
   356  | name | string | File name. |
   357  | mime | string | MIME type. |
   358  | digest | string | SHA256 digest of unencoded payload. |
   359  | payload | string | File content, base64 encoded. |
   360  
   361  ### `Censorship record`
   362  
   363  Contains cryptographic proof that a record was accepted for
   364  review by the server. The proof is verifiable by the client.
   365  
   366  | Field | Type | Description |
   367  |-|-|-|
   368  | token | string | Random censorship token that is generated by the server. It serves as a unique identifier for the record. |
   369  | merkle | string | Ordered merkle root of all files in the record. |
   370  | signature | string | Server signature of the Merkle+Token. |
   371  
   372  ### `Timestamp`
   373  
   374  Contains all of the data required to verify that a piece of 
   375  record data was timestamped onto the decred blockchain.
   376  
   377  All digests are hex encoded SHA256 digests. The merkle root can be found
   378  in the OP_RETURN of the specified DCR transaction.
   379  
   380  TxID, MerkleRoot, and Proofs will only be populated once the merkle root
   381  has been included in a DCR tx and the tx has 6 confirmations. The Data
   382  field will not be populated if the data has been censored.
   383  
   384  | Field | Type | Description |
   385  |-|-|-|
   386  | data | string | Json encoded. |
   387  | digest | string | Timestamped digest. |
   388  | txid | string | Transaction ID. |
   389  | merkleroot | string | Merkle root. |
   390  | proofs | [][`Proof`](#proof) | Timestamp proofs. |
   391  
   392  ### `Proof`
   393  
   394  Contains an inclusion proof for the digest in the merkle root. All
   395  digests are hex encoded SHA256 digests.
   396  
   397  | Field | Type | Description |
   398  |-|-|-|
   399  | type | string | Proof type. |
   400  | digest | string | Timestamped digest. |
   401  | merkleroot | string | Merkle root. |
   402  | merklepath | string | Merkle path. |
   403  | extradata| string | Json encoded extra data, used by certain types of proofs to include additional data that is required to validate the proof. |
   404