Hypermedia Support - discovery and navigation

What is it?

Hypermedia is a means of providing contextual information about data returned from an API call, with every API call available. This allows a consumer to not only retrieve the data specific to the API call, but also to view related contextual information about the data such as how to drill down into the detail of an item, or how to go to the next page of a list of items.

Note: Listed here is a list of currently supported hypermedia related types.

Hypermedia can have many ways of being represented (see technical articles such as Json-LD, HAL or Collection+JSON). However, due to the volatility of the current implementations, Saasu have decided to adopt a simple approach initially that is loosely based of the HAL format to allow for easier migration to formal standards in the future.

With the Saasu API, each response entity (whether a list of items, or a single item) contains a "_links" element, that is a collection of links to related items of the specific entity.

Each related link contains the following elements:

  • rel: Indicates what kind of relation this data is to the entity
  • href: Indicates the Uri required to access this related data
  • method: Indicates the HTTP method required to be used when accessing the Uri (for example POST, PUT, DELETE, or GET)

To clatify, the example below shows an API call made to retrieve a list of accounts (https://api.saasu.com/accounts).

The data returned shows regular data structures for a list of accounts (with the majority of data omitted for brevity) but within each data structure is a "_links" element, that contains one or more related links.

As shown below, within the list of accounts, each account listed also contains a "_links" element with an item showing how to drill down to get the detail of the record as denoted by the "rel" element with a value of "detail".

Additionally, a "_links" element is also added to the root of the returned data to indicate related actions such as how to access the next page of data (as denoted by the "rel" element with a value of "next". The related "self" item (as denoted by the "rel" element with a value of "self") shows the action that was performed to return this data. That is, the call that was made.

The "href" element within each item of the "_links" structure refers to the url required to access the resource. if additional query arguments are present in the url when making the call, these are also represented in the "href" element.

Finally, each "_links" item contains the "method" element to indicate what type of HTTP call should be made. The values can be either GET, PUT, POST or DELETE. 

            {
              "Accounts":[
                {
	              "Id":9,
	              "Name":"Data Services",
	              "AccountType":"Income",
	              ....rest of data structure...
	              "_links":[
                        {
                            "rel":"detail",
                            "href":"https://api.saasu.com/account/9?fileid=123",
                            "method":"GET",
                            "title":null
                        }]
	            },
	            {
	              "Id":11,
	              "Name":"Telco - Telephone",
	              "AccountType":"Expense",
	              ....rest of data structure...
	              "_links":[
                        {
                            "rel":"detail",
                            "href":"https://api.saasu.com/account/11?fileid=123",
                            "method":"GET",
                            "title":null
                        }]
	            },
	            "_links":[
	              {
                        "rel":"self",
                        "href":"https://api.saasu.com/accounts?fileid=123",
                        "method":"GET",
                        "title":null
	              },
	              {
                        "rel":"next",
                        "href":"https://api.saasu.com/accounts?fileid=123&page=2&pagesize=25",
                        "method":"GET",
                        "title":null
	              }
	            ]
            }

Detailed list of supported Hypermedia related links

The following list shows the current supported hypermedia related items. In practical terms, the values listed represent the range of values that may be returned as the "rel" element.

  • "self":
  • "deprecated": Indicates this API call is deprecated and a newer one is available. Eventually this call will be phased out.
  • "detail": Indicates the API call required to obtain details of the item with which it is associated.
  • "insert": Indicates the API call required to insert a resource of the associated type.
  • "list": Indicates the API call required to obtain a list of items of the associated type.
  • "next": When listing a series of items for a resource, this indicates the API call to make to retrieve the next page of items.
  • "previous": When listing a series of items for a resource, this indicates the API call to make to retrieve the previous page of items.
  • "update": Indicates the API call to make when performing an update of associated resource.
  • "header": Links to the header account for the requested detail account.
  • "related": Indicates that this API call contains links to related resources. The href will show the link required to access this related resource and the 'title' will be the title of the relation. supported title values are 'BillingContact' , 'ShippingContact' , and 'Company'.