An API is a user interface. It just happens that the user is another machine. Therefore they are subject to be applied usability and user experience techniques: if it was a graphical user interface, we would be talking about a nice, eye-candy look 'n' feel and dynamic, interactive behavior. However, for RESTful APIs this means providing auto-discoverable, dynamic and self-documented operations and properties. How can we do that? The answer is hypermedia-based APIs implementing the HATEOAS pattern.
Before anything else, this post is not about describing the details of this architectural style. Although it is important to mention that there is a lot of controversy about hypermedia-based APIs (is HATEOAS a solution looking for a problem?), I also like to remember that the pattern itself makes sense. It lets you focus on modelling the problem's domain and let the consumers find about it dynamically. This means total decoupling, the nirvana of Systems Architecture. And if you are worried about the chattiness of your interactions, remember that combining HTTP/2 and advanced content negotiation makes HATEOAS way less silly. As the author of the previous post mentions "maybe you can remove the "ish" from your RESTish APIs by focusing more on your API as a state machine now that you're not quite as scared of making more HTTP calls".
Browsing auto-discoverable APIs
Hypermedia-based APIs are the Iberian lynx of software: they are difficult to spot in the wild, although there are very good examples. Actually, this architectural style is the keystone of our vision and value proposition at DXC Technology.
This is DXC Technology's proposal to the community: a digital platform where we are making product APIs available for co-innovation with partners and customers. In this context, DXC Technology's tooling is helping them understand hypermedia-based APIs and more importantly, is letting them try these APIs through an interactive Web console integrated into a developer portal. This console provides an interactive, à la Swagger UI user interface to dynamically navigate and discover hypermedia-based APIs fully based on HTTP OPTIONS and both the JSON:API and JSON hyperschema specifications.
As a step forward, today we are announcing that DXC Technology is releasing this tooling as an open source project known as Halstack: a set of tools to help developers build applications consuming hypermedia-based APIs.
Halstack Browser
Halstack Browser is a React component that can be included in any React Web App and provides a visual mechanism to crawl and discover API resources and operations dynamically for hypermedia-based APIs. In contrary to other path-based approaches such as OpenAPI (where static specs are used to describe a list of pre-defined path resources and available operations) Halstack Browser allows both API consumers and producers work with auto-discoverable REST APIs just based on their implementations, without any spec. Thus, every time an API implementation changes, these updates will be automatically visible in Halstack Browser Web component without the need of importing or configuring any API spec.
Halstack Client
Halstack Client for JavaScript enables developers to easily work with hypermedia-based APIs programmatically. It offers a set of functionalities to facilitate the navigation between hypermedia resources and get access to their properties dynamically, based on the JSON:API and JSON Hyperschema specifications.
This SDK is released as a client-agnostic library that can be used in many different types of consumers: browser applications (such as React Applications in combination with Halstack Browser) or backend applications (node.js applications or AWS Lambdas).
Summary
Try Halstack Browser with your hypermedia-based API at this online demo. You will find that it is incredibly easy to use and it will help you see hypermedia-based APIs differently. We hope Halstack helps you and your customers gain a better understanding of self-documented, implementation-driven RESTful APIs.
Halstack is open for collaborations at github.com. We are eager to read your comments.
Top comments (0)