Almost all Web API responses contain a JSON object that will contain some combination of the following four root-level keys:

• meta: containing metadata information about the request such as status, trace_id, etc.,
• data: contains the requested data, if any,
• errors: an array of one or more error objects,
• results: returned only in batch-based methods, contains data or errors keys.

The exact keys returned depends upon the type of API being called and the result. Batch-based APIs, that can handle a number of requests at once have a different response pattern than regular APIs. Also, if there are errors, then the response pattern will be different.

Regular APIs

Regular APIs are those APIs that handle a single request at a time. The vast majority of the APIs in the Kompliant Web API are regular APIs.

meta

Regular APIs will always include a metakey and the status field within. This field will be either SUCCESS or ERROR depending upon the result of the API call. This is used in addition to the HTTP status codes. SUCCESS will correspond with HTTP status code 200. Any other status codes will be ERROR.

Most responses will the trace_id and version fields. However, infrastructure responses, as defined in the HTTP status codes documentation may not include these two fields.

Additional fields may be included in the meta key as appropriate. For example a warnings array may be returned if the response includes warnings, such as if an API is deprecated.

data

If the response is successful (as seen in the meta.status field), then the data key will be returned, even if no data is being returned. The contents of data will be documented by the particular API.

This array is only returned if the meta.status is SUCCESS.

errors

If the response is a failure (as seen in the meta.status field), then the errors array will be returned. It will contain one or more error objects. error objects contain at least two fields: code and message. code will be an ENUM string defined either in the Standard Errors documentation or in the API documentation itself. message will be a plain language description of the error. It can contain other fields as defined by the particular error or API.

This array is only returned if the meta.status is ERROR.

Batch APIs

Batch APIs are APIs where multiple requests are handled within the single API call. Batch APIs pose a particular challenge for the caller to align the requests with the responses, especially if some requests succeeded and some failed. The following fields in the response are used to identify exactly which requests succeeded and which failed, while also providing consistency across various APIs.

meta

Batch APIs will always include a metakey and the status field within. This field will be either BATCH_PROCESSED or ERROR depending upon the result of the API call. This is used in addition to the HTTP status codes. BATCH_PROCESSED will correspond with HTTP status code 200. Any other status codes will be ERROR. BATCH_PROCESSED indicates that the whole batch was processed. ERROR indicates that the whole request failed, such as if not authenticated.

Most responses will the trace_id and version fields. However, infrastructure responses, as defined in the HTTP status codes documentation may not include these two fields.

Additional fields may be included in the meta key as appropriate. For example a warnings array may be returned if the response includes warnings, such as if an API is deprecated. Other batch response may include total_requests, success_count, and failure_count to provide statistics about the result of the batch request.

results

Instead of the data field, batch responses will return a results array of result objects. The result object will contain a status field, a request objects, and either a data object or errors array.

The status field will be either SUCCESS or ERROR to indicate if this particular item succeeded or failed.

The request object will echo back some or all of the fields of this particular items; the values returned will be enough to correlate the request to the response.

The data object will contain the results of the particular batch item, or be empty if no result is returned. The exact values returned will be defined in the particular API. This field is only returned if the status is SUCCESS.

The error array will contain one or more error objects. error objects contain at least two fields: code and message. code will be an ENUM string defined either in the Standard Errors documentation or in the API documentation itself. message will be a plain language description of the error. It can contain other fields as defined by the particular error or API. The error array is only returned if the particular batch item request's status is ERROR.

The results array is only returned when the whole batch response status (found in meta.status) is BATCH_PROCESSED.

Note, that if every individual request in the batch request failed, the meta.status value will still be BATCH_PROCESSED. The value of ERROR in meta.status is only returned if the batch as a whole could not be processed, such as with an unauthenticated call.

errors

If the whole batch request is a failure (as seen in the meta.status field), then the errors array will be returned. This will be the case if the request as a whole cannot be processed, such as in an unauthenticated call. If every individual request in the batch request failed, the meta.status value will be BATCH_PROCESSED and the errors array will not be returned. The caller should examine each response in the results array to determine the cause for each failure.

The errors array will contain one or more error objects. error objects contain at least two fields: code and message. code will be an ENUM string defined either in the Standard Errors documentation or in the API documentation itself. message will be a plain language description of the error. It can contain other fields as defined by the particular error or API.

This array is only returned if the meta.status is ERROR.