This post is in my Self Descriptive HTTP API in ASP.NET Core series. It demonstrates how to design an HTTP API like a regular HTML website. Bringing the concepts of links and actions to your API allows your clients to consume it with ease.
If you’re new to this series, here are earlier posts to get up to speed:
You probably have already heard the term hypermedia before. Hypermedia and Hypertext are nothing new. They were both coined in the 60’s by Ted Nelson.
You’ve definitely used hypermedia in the form of HTML.
HTML has a great set of tags that represent hypermedia.
When you are writing HTML and using
<script> tags you are proving information to the client about other navigation or actions they can perform.
Your browser is nothing more then a hypermedia client that understands HTML. In the case of
<form> the end user behind the browser ultimately decides if they are going to follow those links or submit the form. You generally hit a a website either by navigating from another site, or manually enter the URI in your browsers address bar. You then navigate the site via links and forms. I generally don’t see people typing in every URI in there browser address bar 🙂
Googlebot (web crawler) is another great example of a hypermedia client that understands HTML. It follows
<a> tags through your site to crawl all the exposed pages. Googlebot doesn’t know how to craw a random URI on your site unless you tell it.
It’s not magic. It’s about returning a media type (content-type) and payload the client can understand.
What I find really interesting is even with how successful HTML is the popularity of using hypermedia in our HTTP API’s seems really low.
It’s not because of lack of media types. HAL (Hypertext Application Language) was the first media type I discovered when starting thinking about the idea of linking one URI to another in my HTTP API.
I was late to the party since these ideas started coming to me several years after HAL was created in 2011.
Since then have been other media types that have gained some traction:
Following CQRS, I expose commands and queries and URIs. Some media types like HAL don’t really give me the ability to specify how to perform various actions (commands) with payloads a user can invoke in the system.
However, a media type like Siren does. The general idea can really be related to an HTML
Here is a basic HTML form. If you were creating an client that understood HTML you would be able to easily create a HTTP request to perform the action.
The above form describes an action. If we wanted to create an HTTP request to submit this action, we have all the information in the form to build the request.
- The URI is by action=”/books/add”
- The HTTP verb used whith the method=”post”
- The body of our request is defined by the <input> and <select> elements
- The select <option>’s define valid valid for the price
Because we understand HTML specification, we can easily create the HTTP request as:
By using a media type like Siren we can start to develop HTTP APIs that are self descriptive.
It’s a combination of the content type and the message body that makes our API self descriptive. You cannot just return arbitrary JSON and expect your clients to understand how to use it. They must understand what the content is.
— Darrel Miller (@darrel_miller) April 20, 2017
To the code! In my next post I’m going to start providing some sample code for creating an HTTP API in ASP.NET Core using Hypermedia.
If anyone has any other suggestions or recommendations about this series, please leave comment or let me know on twitter.