Request and Response Patterns

The API follows industry norms around JSON-based REST APIs.

Requests

• All POST and PUT requests support JSON as the data format (application/json)

• Updating objects (with PUT) use "sparse" update semantics (only properties that are provided in the request will be changed)

• Many requests support a select query string parameter which is used to include or exclude additional information in the response. For example:

  • ListClients: by default does not include contact information for clients but can include this by providing select=contact on the query string

  • Most list endpoints does not include date stamps but this can be included by adding select=meta on the query string. This will include information about when the item was created and modified in a meta property.

  • Multiple selects can be comma separated, and items included by default can excluded with a hyphen. For example select=contact,-meta will include contact information but exclude metadata.

Responses

• All responses are wrapped in a standard JSON object, with the return object or lists of objects in the data property

Code
 
{ 
  "data": {
    "id": 123,
    "name": "tim" 
  } 
}

• Most endpoints that return lists of objects are paginated. The maximum number of items returned in a request is 1,000. Pagination is controlled by the query parameters limit (number of items returned) and offset (starting index of item). The returned list will contain a pagination property containing the total number of items. In this example, 1,000 items are returned but there are 1,543 more:

Code
 
{ 
  "data": [
    ...
  ], 
  "pagination": { 
    "limit": 1000,
    "offset": 0,
    "total": 2543
  }
}

HTTP Status Codes

• GET, PUT, and DELETE requests return a 200 status code if successful

• POST requests return 201 status code if successful

• 401 - missing authentication (no API key provided)

• 403 - the token is not authorized to performance the action or is invalid

• 429 - throttling. The caller has issued to many requests. Initiate a backup retry strategy

• 400 - invalid request (bad parameters or invalid request data)

• 500 - server-side error. Please notify us if this happens

All responses contain a trace id in the header that is helpful if you need help understand why a request is not working as intended or causing an error:

Code
 
x-leanlaw-traceid: {id}