REST API Discoverability

by

As part of the REST with Spring Series series, we will discuss REST API Discoverability, HATEOAS. We will discuss different scenarios and the real-life use cases for the discoverability of the REST API.

 

Introduction

Making a discoverable REST API means that system should be able to traverse complete API by only pointing to the root API.This is an important design for a REST API and often ignored by many RESTful APIs. In this article, we will discuss

  • Why make the REST API discoverable?
  • How to make a REST API discoverable.

 

1. Why make the REST API Discoverable

Making the REST API discoverable is often overlooked. Discoverability helps to make RESTful API more useful and elegant.API discoverability is related to HATEOS, this concept of REST API is about full discoverability on a Resource from Hypermedia. Let’s look at some important points to understand the need to making REST API discoverable.

  • With this feature, REST API providing full URI’s in the responses to the client means that no client will ever need to “compose” a URI.
  • Client API become independent from the URI structure.
  • With above 2 points, API is more flexible and allow the developer to change URI schema without breaking API. (Remember, API provides all URI, they are not created dynamically by the client API).

The end goal of any RESTful API is self-explanatory such that client API does not have to have prior knowledge of a formal contract to consume your content/functionality.

[pullquote align=”normal”]Discoverability is all about enabling people to learn and use the API. [/pullquote]

 

2. Discoverability API Example

To understand the discoverability of the REST API, let’s take an example of the GitHub REST API.On opening the following URI https://api.github.com, we get the following output

{
  "current_user_url": "https://api.github.com/user",
  "current_user_authorizations_html_url": "https://github.com/settings/connections/applications{/client_id}",
  "authorizations_url": "https://api.github.com/authorizations",
  "code_search_url": "https://api.github.com/search/code?q={query}{&page,per_page,sort,order}",
  "commit_search_url": "https://api.github.com/search/commits?q={query}{&page,per_page,sort,order}",
  "emails_url": "https://api.github.com/user/emails",
  "events_url": "https://api.github.com/events",
  "feeds_url": "https://api.github.com/feeds",
  "followers_url": "https://api.github.com/user/followers",
  "following_url": "https://api.github.com/user/following{/target}",
  "gists_url": "https://api.github.com/gists{/gist_id}",
   ..................
  "user_url": "https://api.github.com/users/{user}",
  "user_organizations_url": "https://api.github.com/user/orgs",
  "user_repositories_url": "https://api.github.com/users/{user}/repos{?type,page,per_page,sort}",
  "user_search_url": "https://api.github.com/search/users?q={query}{&page,per_page,sort,order}"
}

This is an interesting example and covers multiple points discussed in the earlier section. Let’s reiterate these points once again.

  • While linking to the root endpoint, we have the context of entire API.
  • The client should be able to traverse entire API from the root endpoint by following the links.
  •  As a consumer, we need not build logic to create endpoint URI’s as they will be available from the root endpoint.
  • REST API have more flexibility to change the individual URIs.

Let’s look at more example to understand the importance and usefulness of making our REST API discoverable.I will use GitHub API for our post examples.

 

2.1. Discover the URI of newly created Resource

A well-designed REST API should always include URI of the newly created resource on the response. This will help the customer to navigate to the new resource if needed.Let’s create a new public repository on the GitHub. As part of the discoverability feature, we are expecting following data in the response.

  • Status code for the request processing.
  • URI of the newly created repository (resource in the REST terminology) using HTTP Location header.

Here is our request for creating a new repository on the GitHub

{ https://api.github.com/user/repos?access_token=xxxxxxx
  "name": "Hello-World",
  "description": "This is your first repository",
  "private": false,
  "has_issues": true,
  "has_projects": true,
  "has_wiki": true
}

We got success response back from GitHub API with following data in the response

Status: 201 Created
Location: https://github.com/xxxx/Hello-World
----------------------------------------------------------
{"id": 131447234,
"name": "Hello-World",
"full_name": "xxxx/Hello-World",
"owner": {
  .......
},
"private": false,
"html_url": "https://github.com/xxxx/Hello-World",
"description": "This is your first repository",
"fork": false,
..........
"subscribers_count": 1
}

In the above response, GitHub sends back all the information of the newly created repository.One of important information passed under Location HTTP header. If the client performs GET request on the URI sent back under Location header, the resource should be available.

 

2.2. Discover All Resources of Given Type

When pulling resource of a certain type, RESTful API should provide information in the response URI to retrieve all resources. The response of the REST API should have following information.

  • Link to retrieve all the resources.
  • Information to move to the next resource.
  • The total number of resources available in the system.

There are 2 ways to meet this goal

  • Embed link/information in the response body.
  • Use HTTP Link header.

HTTP headers are a critical aspect of RESTful API integrations and we are taking this approach in this example. Let’s send a request to GitHub to give the list of all the repository associated with a user

https://api.github.com/user/repos?access_token=xxx

We got success response from GitHub API with following data in the response

Status: 200 OK
Link: <https://api.github.com/user/repos?page=2>;rel="next", <https://api.github.com/user/repos?page=2>; rel="last"
----------------------------------------------------------
{"id": 131447234,
"name": "shopizer",
"full_name": "shopizer-ecommerce/shopizer,
"owner": {
  .......
},
..........
}

 

Summary

In this article, we discuss REST API Discoverability. We discussed why to make a REST API Discoverable and how a REST API is fully discoverable from the root and with no prior knowledge. API Discoverability is often overlooked while designing and creating REST API’s but this can work as a powerful tool for the REST APIs.

Comments are closed.