Basic Concepts

When using the ASSIST APIs, there are a number of concepts that will be consistent with each of the APIs. These concepts will be commonly used when communicating with any of the APIs.

API Key

In order to use the ASSIST APIs, an API key is required. This key will be a unique identifier that is generated and provided for you to use when making calls to the APIs.

An example of an API key would be: f9bab42d-b42f-48dd-9143-eacdadd67192

Each request you make needs to have this key provided in an HTTP Header named API-Key. If you do not provide this key, the APIs will not accept your request and you will receive a 401 response (unauthorized).

Request / Response Formatting

All of the ASSIST APIs will accept and reply in JSON format. Other formats are not supported at this time, such as XML. Each of the APIs documented here will provide the format structure for both request and response bodies.

Common Response Structure

All of the ASSIST APIs use a common response structure for provided a consistent format for when there is an issue with your request. For example, if a request has a required parameter and it is not provided, a validation error will be returned. The common structure is as follows:

{
  "result": null,
  "validationFailure": { },
  "isSuccessful": false
}

isSuccessful

(True/False) Indicates if the request was successful or not

result

When a request is successful, this property will contain the resulting data. When a request is not successful, this property will be null. The type and structure of the result is specific to each API.

validationFailure

When a request is not successful, this property will contain one or more validation errors that prevented the request from being processed. When a request is successful, this property will be null.

There are some cases where this format is not used. Where this the case, the documentation for that API will specify.

Validation Failures

When a request is unable to be processed, the validationFailure property on the result structure will be populated with one or more errors. These errors can be used to diagnose problems with your request. Validation failures will be returned in the following format:

{
"result": null,
"validationFailure": {
    "errors": [
      {
        "propertyName": "PropertyA",
        "errorMessage": "Record was not found",
        "attemptedValue": "123"
      }
    ]
},
"isSuccessful": false
}

errors

This property contains an array of errors found with the request. Each error will have information about the problem that was found.

Error Properties

propertyName

Contains the name of the property from the request that was invalid

errorMessage

Specifies the error, or issue, with the value that was specified

attemptedValue

Contains the original value that was attempted in the request

Additional properties will be present as part of a validation failure result however, these properties can be ignored as they do not provide any additional context.

System Exceptions

In some cases it is possible that you will receive a system exception. In these situations you will receive a response with the following content:

{
    "message": "Oops, something went wrong! Check the logs for more information."
}

While there are a wide variety of scenarios where this situation can occur, it should be rare. In the event that is does, please contact us help@assist.org.

Http Status Codes

The following are a range of possible status codes you may receive from the ASSIST APIs while making requests.

200

OK - Valid and successful request.

400

Bad Request - There was a validation error with your request. Check the validationFailure.errors property for more details. 401

Unauthorized - The API key you attempted to use was invalid.

404

Not Found - The specified URL or record you were looking for was not found.

406

Not Acceptable - The format of the data provided in your request does not match what was expected. This is often caused by incorrectly formed JSON data.

500

Server Error - An exception was thrown by the system attempting to handle the request.