How our API responses are structured

This guide details how our API returns data and failure states in a standardised format.

Contents

  1. Introduction
    1. Response types
  2. Examples
    1. Success
    2. Fail
    3. Error

# Introduction

Intelligence Fusion APIs are used to query data from the platform, e.g. Incidents.

Our APIs are structured around RESTful principles, enabling our APIs to be both flexible and consistent.

All responses from our APIs are structured following the JSend specification, this guide is based upon this document. The JSend specification defines how API responses are structured, as well as how error/failure states are represented via the APIs.

Following the JSend Specification ensures that all responses from Intelligence Fusion’s APIs are consistently structured, this enables developers to quickly integrate the API in a consistent fashion.

# Response types

Responses are seperated into some basic types, with required and optional keys for each type:

Type Description Required Keys Optional Keys
successAll went well, and (usually) some data was returned.status, data
failThere was a problem with the data submitted, or some pre-condition of the API call wasn't satisfiedstatus, data
errorAn error occurred in processing the requeststatus, messagecode, data

# Examples

The following examples are derived from the above JSend specification, tailored to how this specification is used by Intelligence Fusion.

# Success

When an API call is successful, the JSend object is used as a simple envelope for the results, using the data key, as in the following:

GET /geography/countries:
{
  "status": "success",
  "data": {
    "countries": [
      {
        "code": "USA",
        "alpha2": "US",
        "name": "United States",
        "continent": {
          "code": "NA",
          "name": "North America"
        }
      }
    ]
  }
}
GET /geography/countries/USA:
{
  "status": "success",
  "data": {
    "country": {
      "code": "USA",
      "alpha2": "US",
      "name": "United States",
      "continent": {
        "code": "NA",
        "name": "North America"
      }
    }
  }
}

# Fail

When an API call is rejected due to invalid data or call conditions, the JSend object’s data key contains an object explaining what went wrong.

For example, when an invalid access token is provided to an endpoint that requires authentication:

{
  "status": "fail",
  "errors": [
    {
      "code": 1,
      "message": "Invalid token"
    }
  ]
}

Required keys:

  • status: Should always be set to “fail”.
  • data: Again, provides the wrapper for the details of why the request failed. If the reasons for failure correspond to POST values, the response object’s keys SHOULD correspond to those POST values.

# Error

When an API call fails due to an error on the server, for example:

{
  "status": "error",
  "message": "Internal Server Error"
}

Required keys:

  • status: Should always be set to “error”.
  • message: A meaningful, end-user-readable (or at the least log-worthy) message, explaining what went wrong.

Optional keys:

  • code: A numeric code corresponding to the error, if applicable
  • data: A generic container for any other information about the error, i.e. the conditions that caused the error, stack traces, etc.