Responses

Format

All responses are returned in a format of JSON called Hypertext Application Language (HAL). Responses are composed of three parts:

_embedded

An object that contains embedded resources.

      Example _embedded property
    
{
  "_embedded": {
    "tags": [
      {
        "_links": {
          "self": {
            "href": "/tags/229"
          }
        },
        "id": 229,
        "type": "tag",
        "name": "space exploration"
      }
    ]
  }
}

_links

An object that contains links to related resources.

      Example _links property
    
{
  "_links": {
    "self": {
      "href": "/articles/8841"
    },
    "related_content": [
      {
        "href": "/articles/8790"
      }
    ]
  }
}

Resource data

The data of the primary resource.

      Example resource data
    
{
  "id": 8841,
  "type": "article",
  "publish_date": 1436464500,
  "headline": "Pluto shows its heart ahead of New Horizons close-up"
}

Types of responses

We have already alluded to objects, but there are three types of responses you may encounter when using the API:

An object: a response that contains a single resource.
A collection: a response that contains a set of resources.
An error: a response indicating something went wrong.

Objects

To illustrate how the three parts of a HAL response are used in object responses, take a look at this truncated article object:

      GET /articles/8841
    
{
  "_embedded": {
    "tags": [
      {
        "_links": {
          "self": {
            "href": "/tags/229"
          }
        },
        "id": 229,
        "type": "tag",
        "name": "space exploration"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/articles/8841"
    },
    "related_content": [
      {
        "href": "/articles/8790"
      }
    ]
  },
  "id": 8841,
  "headline": "Pluto shows its heart ahead of New Horizons close-up",
  "publish_date": 1436464500,
  "type": "article"
}

The _embedded property contains an array of tags that are embedded within the article resource. The _links property contains a self link, which is a reference to the article itself, and an array of related_content links, which point to resources that are topically related to the article. The remaining properties are resource data points that describe the article itself: id, headline, publish_date, and type.

Collections

To illustrate how the three parts of a HAL response are used in collection responses, take a look at this truncated article collection:

      GET /articles?page=2
    
{
   "_embedded": {
      "articles": [
         "...article object...",
         "...article object...",
         "...article object...",
         "...article object...",
         "...article object..."
      ]
   },
   "_links": {
      "find": {
         "href": "/articles/{?id}",
         "templated": true
      },
      "next": {
         "href": "/articles?page=3"
      },
      "prev": {
         "href": "/articles?page=1"
      },
      "self": {
         "href": "/articles?page=2"
      }
   },
   "page": 1,
   "per_page": 5,
   "return_count": 5,
   "total_available": 100
}

The _embedded property contains an array of article objects, truncated for illustrative purposes. In the real-world version of the response, ...article object... is an entire article resource.

The _links property contains four links that are related to the collection:

find: A templated link that can be used to find a specific resource in the collection.
next: A link to the next set of resources in the collection. If there is not a next page, this link will not be present.
prev: A link to the previous set of resources in the collection. If there is not a previous page, this link will not be present.
self: A link that identifies the current resource.

The remaining properties are resource data points that describe the collection itself: page, per_page, return_count, and total_available. In this example, we are on the first page of the collection, 5 articles were requested, 5 articles were returned, and there are a total of 100 articles available in the collection.

Errors

If a request to the API generates an error, a JSON object of the following format is returned:

      GET /articles?page=one
    
{
  "error": true,
  "message": "Invalid value for `page` query string parameter: 'one'",
  "statusCode": 400
}

The values of the message and statusCode properties will reflect the nature of the error that was generated.

Status codes

Each response from the API will contain an HTTP status code that indicates whether the request was successful. Below is a table containing status codes you may encounter when working with the API.

Status code	Description
200	Successful response.
400	Bad request. Make sure all query string parameters are correctly formatted.
401	Unauthorized. Make sure to provide a valid API key.
403	Forbidden. Your API key is not authorized to access the requested resource.
404	Resource not found.
405	Method not allowed.
503	Service Unavailable. Something went wrong on the server and administrators have been notified.

Pagination

When a collection contains enough resources to allow for pagination, you will find the next and/or prev links in the response:

      GET /articles?page=2
    
{
  "_links": {
    "next": {
      "href": "/articles?page=3"
    },
    "prev": {
      "href": "/articles?page=1"
    }
  }
}

The pagination URIs will contain any query string parameters that were passed with the original request, short of the version number and your API key.

If there is not a previous or next page, these URIs will be omitted from the _links property. For example, on the first page of an article set, there will not be a prev URI:

      GET /articles?page=1
    
{
  "_links": {
    "next": {
      "href": "/articles?page=2"
    }
  }
}