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:
Sponsor: Do you build complex software systems? See how NServiceBus makes it easier to design, build, and manage software systems that use message queues to achieve loose coupling. Get started for free.
Hypermedia ClientsMy 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 BrowsersHowever, 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.
NextLooking 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/cf2b6d63-9a7f-4dc6-9989-f12bb8af7715If 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 Clients