Specifications for Record APIs¶

APIs of the Records type provide the detailed information of records. Before registering the Records APIs as the data sources in Common Data Service, you need to standardize the APIs according to the following specifications.

Note

In addition to the parameters defined below, Common Data Service can additionally pass some static parameters to support routing within the API provider. Contact the system administrator for parameter specification details.

HTTP Method¶

POST

Request Parameters¶

Name	Mandatory/Optional	Data Type	Description
orgId	Mandatory	String	The organization ID which the record belongs to.
locale	Optional	String	Use zh-CN, en-US, ja-JP, or es-ES. If not specified, the value is set to en_US by default.
fields	Optional	String	The field of the record. Separate multiple fields by commas. When multiple records in a single query is supported, these records must have the same fields and at least one of these fields supports sorting. This field is used for secondary sorting, which supports only the results on the first page.
filter	Optional	String	Filter the returned data based on the expression. For example, [[{“field”:”field1”,”operator”:”>=”,”value”:”1”},{“field”:”field2”,”operator”:”<=”,”value”:”2”}],[{“field”:”field3”,”operator”:”==”,”value”:”3”}]], which means the returned data is filtered by (field1 >= 1 and field2 <= 2) or (field3=3). If the operator in the expression is in and the value contains multiple values, separate the values by commas. If a value itself contains a comma, escape the comma from value.
orderBy	Optional	String	Sort the returned data based on the expression. For example, [{“field”:”field1”,”order”:”ASC”}, {“field”:”field2”,”order”:”DESC”}], which means the returned data is sorted first by field1 in ascending order and then by field2 in descending order. If no expression is specified, the default sorting method is determined by the API provider.
pageSize	Optional	Integer	The number of the returned records on a single page. A minimum of 1000 is supported and the default value is determined by the API provider.
pageNo	Optional	Integer	The number of page to be returned. The default value is 1. If pageNo is greater than the total number of pages, return an empty list.

Response Parameters¶

Name	To Return Definitely/Conditionally	Data Type	Description
recordFields	Definitely	Record Fields Struct	Describe the detailed record information.
pagination	Definitely	Pagination Struct	Describe the pagination information. See Pagination Struct.

Pagination Struct ¶

Name	To Return Definitely/Conditionally	Data Type	Description
pageNo	Definitely	Integer	The number of page to be returned, starting from 1.
pageSize	Definitely	Integer	The number of the returned records on a single page.
totalSize	Definitely	Integer	The total number of the returned records.

Request Content Type¶

application/json; charset = UTF-8

Response Content Type¶

application/json; charset = UTF-8

Request Sample¶

POST {requestURL}?orgId=yourOrgId&locale=yourLocale
Content-Type: application/json
Payload:
{
    "fields": "a,b,c",
    "filter": [[{"field":"field1","operator":">=","value":"1"},{"field":"field2","operator":"<=","value":"2"}],[{"field":"field3","operator":"==","value":"3"}]],
    "orderBy": [{"field":"field1","order":"ASC"}, {"field":"field2","order":"DESC"}],
    "pageSize": 100,
    "pageNo": 1
}

Response Sample¶

{
    "data": [
        {
            "field1":"examplefield1",
            "field2":"examplefield2",
            "field3":"examplefield3"
        },
        {
            "field1":"examplefield1",
            "field2":"examplefield2",
            "field3":"examplefield3"
        }
    ],
    "pagination": {
        "pageNo": 1,
        "pageSize": 10,
        "totalSize": 100
     },
    "code": 0,
    "msg": "OK"
}