Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

An Example of an API Service Provider Using Hypermedia

DZone's Guide to

An Example of an API Service Provider Using Hypermedia

The AWS API Gateway API is a well designed, highly functional API for managing the operations of your API. AWS is putting hypermedia to good use.

· Integration Zone
Free Resource

Modernize your application architectures with microservices and APIs with best practices from this free virtual summit series. Brought to you in partnership with CA Technologies.

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.

The Integration Zone is proudly sponsored by CA Technologies. Learn from expert microservices and API presentations at the Modernizing Application Architectures Virtual Summit Series.

Topics:
hypermedia ,api ,aws api gateway ,api providers ,integration

Published at DZone with permission of Kin Lane, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}