Every API response must be mapped to the following format:
{
success: true,
data: [
{ id: 1, name: 'Joe', addresses: [] },
{ id: 2, name: 'Jane', addresses: [] },
],
meta: {
authenticated: true,
cursor: 'https://foo.com/2345243523452345235234523452',
tooManyRequests: false,
retries: 0,
response: {},
action: {
id: 'actionId',
slug: 'actionSlug',
operation: 'Create',
query: {},
body: {}
}
}This format, and most mappers, exist because many APIs are nonstandard and do not conform to expected format. The format above enables all subsequent functionality within Gravity to occur with the needed automation.
It’s the App Developer’s responsibility to ensure that all API responses are mapped properly to the above format
Format Details
success must always exist as a boolean indicating whether the action was successful or failed.
Some APIs will properly return a non-200 http status in case of failure, in this case success will be false. However, there are sometimes false positives or negatives. A common example is that an API's GET [Contacts] request will return a 404 if there are no contacts and therefore success is false. It's up to you to return success as true and just return an empty array in the data.
data []should always be an array of results that came back from the action. If there are no results, it should be an empty array. Many API endpoints give a nested payload, such as:
{
results: {
Companies: []
}
}It's the responsibility of the mapper to pull the data out of the nested payload and return it as an array at the top level.
meta {}is basically any additional data that is tacked onto the request, which Gravity uses to help in debugging, or for additional functionality relating to the request. It's the responsibility of the mapper to pull out unstructured data from the response and properly tag it in meta {} .
meta.authenticated indicates whether or not the request indicated that an access token expired, or if there is any other reason to re-run the authentication process. This will trigger processes such as the refresh token flow for OAuth 2.0.
meta.cursor is a field that is required for cursor-based pagination, so long as the API response returns a 'cursor' value, which is a string that you send in the next request to get the next page of results. This cursor must be extracted and tagged here for cursor-based pagination to work.
Example: GET /users --- returns 20 users
response: {
users: [] // 20,
cursor: '32423432'
}In this case, we need to mark meta.cursor as 32423432, and on the next request, send GET /users?cursor=32423432 to get the next page of users.
meta.tooManyRequests indicates whether the response has been rate limited. Good apis should return a 429 status code if the rate limit is exceeded. If the API is sloppy and just returns text in the body saying you've been rate limited, it's up to the mapper to tag this in meta {}.
meta.retries is informational, and shows how many times Gravity retried the request after rate limiting, before giving up. This should not be modified.
meta.responseis the raw HTTP response object, and shouldn't be modified.
meta.actionis additional metadata on what action was run and what payloads were sent, which can inform the mapper on how to properly map the response. This should not be modified.
idthe app action IDslugthe app action slugoperationThe operation (create, update, delete, etc.)querythe query parameters sent in the requestbodythe body of the request
One important use of this data is to ensure best practices in API responses. For example, when an object is deleted, it is essential to return the deleted object’s ID in the response. This allows clients to confirm that the correct object was deleted. Poorly designed APIs often omit this information, leading to potential confusion and errors in data handling. You can extract that data from meta.action.query or body and put it in the response data.