How our API responses are structured

Published Sunday, 26 March 2023 by Ryan Howell

api

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

Introduction
1. Response types
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
success	All went well, and (usually) some data was returned.	status, data
fail	There was a problem with the data submitted, or some pre-condition of the API call wasn't satisfied	status, data
error	An error occurred in processing the request	status, message	code, 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"
}