Method types
A JSON RPC method is a named operation that takes as set of parameters and returns a result of a specific type. This is pretty much analogous to a function in programming languages. The main distinction to be aware of is that because the method happens over the wire, and because the input must be validated, all RPC methods may return an error. The spec dictates that a response must either include a result or an error, which means that if a result property is present in the response, your client code can always assume that the method was called successfully, and proceeded without error.
Current methods in Clarify can be grouped into three categories. These are not fixed categories as such, but a way of describing similarities between current methods. Future methods are likely, but not guaranteed, to use similar patterns and principals.
Resource save methods
Resource save methods are methods that create or mutate resources in Clarify. Current save methods follow replace semantics for all attribute fields, while the annotations meta field is merged. All fields to set must appear in a flat format, meaning we do not allow the JSON:API format when writing data through these methods. None of the current save methods allow explicit modification of relationships.
Current methods specify the resources to replace through a mapping by a specific key or relationship, so the generic format for saving resources can be summarized as:
{
"jsonrpc": "2.0",
"id": 1,
"method": "<namespace>.<method name>",
"params": {
"<custom param>": <param value>,
"<resource type>By<field/relationship>": <resource save view>
}
}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"<resource type>By<field/relationship>": <resource save view>
}
}
Read more about resource save views.
Methods that follow this template:
Resource select methods
Select methods are methods allows selecting Clarify resources of a particular type, as well as to side-load related resources. Resources are selected using a Resource query parameter, and inclusions are done by listing the named relationships to include. The result is compatible with the JSON:API list encoding when the "groupIncludedByType" parameter is not set to true. When the parameter exist, the included field in the response will become a map if resource type names to an array of resources. SDKs will typically hardcoded this parameter value, and not expose it to the end-user.
{
"jsonrpc": "2.0",
"id": 1,
"method": "<namespace>.<method name>",
"params": {
"<custom param>": <param value>,
"query": {
"filter": {"<field path>": <comparison>},
"sort": ["<field path>"],
"limit": 10,
"skip": 0,
"total": false // if true, force inclusion of total count.
},
"include": ["<relationship>"],
"format": {
"dataAsArray": true, // set to false to return a single item.
"groupIncludedByType": false // set to true to group included resources.
}
}
}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"meta": {
"total": -1, // total number of results matching filter; -1 means unknown.
"format": {
"dataAsArray": true, // set to false to return a single item.
"groupIncludedByType": false // set to true to group included resources.
},
"issues": {<path issues>}, // Validation issues that doesn't prevent a result, omitted if empty.
},
"data": [<resource select view>],
"included": [<related resource select view>]
}
}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"meta": {
"total": -1, // total number of results matching filter; -1 means unknown.
"groupIncludedByType": true
},
"data": [<resource select view>],
"included": {
"<resource type>": [<related resource select view>]
}
}
}
Read more about resource select views.
Methods that follow this template:
Data methods
Data methods deal with data that's connected to resources. Currently this includes operating on the Data frame type, which is a view for reading and writing time-series data.
Methods in this category include: