Resources representation

HAL is a simple format that gives a consistent and easy way to hyperlink between resources.

You can read the full description of the specification here

Entity

An addressable item being returned. Entities are distinguished by a unique identifier present in the URI.

GET https://api.shopping-feed.com/res/ab77hj9u

{
    "id": "ab77hj9u",
    "createdAt": 1396709084,
    "_links": {
        "self": {
            "href": "/res/ab77hj9u"
        }
    }
}

Collection

A addressable set of entities. Entities contained in the collection are of the same type, and share the same base URI as the collection.

GET https://api.shopping-feed.com/res?limit=2&page=3

{
  "total": 12,
  "limit": 2,
  "pages": 6,
  "page": 3,
  "count": 2,
  "_links": {
    "self": {
      "href": "/res?page=3&limit=2"
    },
    "prev": {
      "href": "/res?page=2&limit=2"
    },
    "next": {
      "href": "/res?page=4&limit=2"
    },
    "first": {
      "href": "/res?page=1&limit=2"
    },
    "last": {
      "href": "/res?page=6&limit=2"
    }
  },
  "_embedded": {
    "res": [
      {
        "id": "ab77hj9u",
        "createdAt": 1496404325,
        "_links": {
          "self": {
            "href": "/res/ab77hj9u"
          }
        }
      },
      {
        "id": "u7t2h5ju",
        "createdAt": 1496404325,
        "_links": {
          "self": {
            "href": "/res/u7t2h5ju"
          }
        }
      }
    ]
  }
}

Pagination query parameters are page and limit. The max number of items per pages is set to 200, value up to this limit will be ignored.

The collection expose properties about pagination info:

  • total Total items count for the resource
  • count Current item number displayed
  • pages Total number of pages for the resource
  • page Current page number
  • limit Current limit used for items count per page

The various relational links for the collection make it trivial to traverse the API to get a full list of resources in the collection. You can easily determine what page you are on, and what the next page should be (and if you are on the last page)

Out of range page request

If an invalide page is requested for the resource, the API will return a ApiProblem Conflict (409) response.

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
    "type":"http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "title":"Conflict",
    "detail":"requested page is out of range",
    "status":409,
    "pages":6,
    "page":100
}

Where:

  • pages The total number of page
  • page The current requested page