An Example of an API Service Provider Using Hypermedia

There is a growing number of hypermedia APIs available in the wild these days. However, there aren't a lot of examples of hypermedia API service providers making the API lifecycle more dynamic and living. When people ask me for examples of hypermedia APIs out there, I like to have a handful of URLs I can share with them, providing a diverse set they can consider as part of their own operations.

One really good example of an API service provider putting hypermedia to use is Amazon Web Services, specifically with the AWS API Gateway.  AWS describes it best in the documentation for the gateway API:

The Amazon API Gateway web service is a resource-based API that uses Hypertext Application Language (HAL). HAL provides a standard way for expressing the resources and relationships of an API as hyperlinks. Using HAL, you use HTTP methods (GET, PUT, POST, DELETE) to submit requests and receive information about the API in the response. Applications can use the information returned to explore the functionality of the API.

If you have used other common AWS APIs like EC2 or S3, then you know that they aren't the best-designed APIs out there. They provide a lot of functionality but leave a lot to be desired when it comes to the actual design. The AWS API Gateway API is a well designed, highly functional API for managing the operations of your API. With each API call, you get the desired response, along with a collection of links defining what else is possible.

{
  "createdDate": "2016-06-01T18:53:41Z",
  "description": "A sample API created programmatically by calling API Gateway control service using the REST API",
  "id": "fugvjdxtri",
  "name": "my-test-api",
  "_links": {
    "self": {
      "href": "/restapis/fugvjdxtri"
    },
    "authorizer:by-id": {
      "href": "/restapis/fugvjdxtri/authorizers/{authorizer_id}",
      "templated": true
    },
    "authorizer:create": {
      "href": "/restapis/fugvjdxtri/authorizers"
    },
    "deployment:by-id": {
      "href": "/restapis/fugvjdxtri/deployments/{deployment_id}{?embed}",
      "templated": true
    },
    "deployment:create": {
      "href": "/restapis/fugvjdxtri/deployments"
    },
    "model:by-name": {
      "href": "/restapis/fugvjdxtri/models/{model_name}?flatten=false",
      "templated": true
    },
    "model:create": {
      "href": "/restapis/fugvjdxtri/models"
    },
    "resource:by-id": {
      "href": "/restapis/fugvjdxtri/resources/{resource_id}{?embed}",
      "templated": true
    },
    "resource:create": {
      "href": "/restapis/fugvjdxtri/resources/3kzxbg5sa2"
    },
    "restapi:authorizers": {
      "href": "/restapis/fugvjdxtri/authorizers"
    },
    "restapi:delete": {
      "href": "/restapis/fugvjdxtri"
    },
    "restapi:deployments": {
      "href": "/restapis/fugvjdxtri/deployments{?limit}",
      "templated": true
    },
    "restapi:models": {
      "href": "/restapis/fugvjdxtri/models"
    },
    "restapi:resources": {
      "href": "/restapis/fugvjdxtri/resources{?limit,embed}",
      "templated": true
    },
    "restapi:stages": {
      "href": "/restapis/fugvjdxtri/stages{?deployment_id}",
      "templated": true
    },
    "restapi:update": {
      "href": "/restapis/fugvjdxtri"
    },
    "stage:by-name": {
      "href": "/restapis/fugvjdxtri/stages/{stage_name}",
      "templated": true
    },
    "stage:create": {
      "href": "/restapis/fugvjdxtri/stages"
    }
  }
}

I wish that all tools in our API toolbox were designed like the AWS API Gateway is. In this single API call, you can see how hypermedia contributes to the life cycle of any API being managed. You can manage access and evolve into a staging or production environment, and take advantage of all of the other possibilities available when each resource is put to work. Instead of having to go back to the API documentation to learn what options are available, they are given to you in a tailored collection of links.

I have already added the AWS API Gateway to my list of hypermedia APIs, but I will now also be referencing as a blueprint of an API service provider who is putting hypermedia to work in their API design. I think hypermedia helps make applications be more flexible and resilient, and I also think hypermedia does the same at the API level, allowing us to more honestly manage change across the API lifecycle.