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. This specific posts covers hypermedia clients.
If you’re new to this series, here are earlier posts to get up to speed:
If you have any questions, please follow me on Twitter.
Hypermedia Clients
My perception is that most people new to hypermedia driven APIs think that consuming hypermedia happens via a magic library.
Or via some code generation that ultimately gives you a client library that understands every endpoint.
I’m not sure why this is, possibly the client code gen libraries behind SOAP/WSDL or Swagger/OpenAPI.
In my experience developing and consuming a hypermedia driven API, there is no magic.
Your consuming client needs to understand the content beyond just the media type for a given URI.
In a custom application, you likely want to show the user specific actions within the UI depending on if the link or action is returned in the API payload.
In our Todo application from my HATEOAS post, the action of marking a Todo item as complete was conditional. It wasn’t available on every Todo item. My UI would likely reflect that.
The same goes with links to other resources, they may or may not be in the payload.
Siren Browsers
However, you can make a generic UI if you use a defined media type.
Since I’ve been using Siren in my previous examples, we will keep with that for a client examples.
These Siren browsers are no different then HTML browsers. They understand the media type and render UI.
What this shows is the ability for you to create re-usable components based on the specifics of the payload your server is returning.
In my Todo example, I could create a specific UI component that is used when retrieving a Todo item from the API.
Siren Client Helper Libraries
You technically don’t need any libraries to start consuming a siren payload. As long as you understand what content inside the siren schema is going to be returned you should be able to deserialize the JSON into your own type and do what you want.
Super Siren is a pretty good example of a Javascript helper library. It has helpers for making HTTP requests and then performing navigation and actions.
Next
Looking ahead I will start to develop our ASP.NET Core client.
As well as discuss why why URLs become opaque.
Meaning there is no difference between
http://domain/api/todo/123
and
http://domain/cf2b6d63-9a7f-4dc6-9989-f12bb8af7715
If anyone has any other suggestions or recommendations about this series, please leave comment or let me know on twitter.
- Building a Self Descriptive HTTP API in ASP.NET Core
- Object as Resource
- Hypermedia
- Siren
- HATEOAS
- Hypermedia Clients