API specification format for hypermedia-centric APIs

[someniatko]

Hi there!

At the company where I currently work, we started adopting a more hypermedia driven approach to our internal APIs, which includes the following changes in contrast to the traditional data-centric APIs.

• using links to cross-reference different resources
• URLs (possibly templated with parameters) are given in the links themselves, instead of being hardcoded in the API client. Therefore, the URLs namespace is fully controlled by the server.
• available actions on a resource are encoded as links as well and are given dynamically by the server, instead of relying on the client to infer them from the resource data (e.g. status fields) thus keeping the client logic to the bare minimum
• a resource response may or may not include related subresources (the server determines if it wants to include them)

Specifically, we are using HAL, and an alternative approach, json:api also exists (but to my taste is much more verbose). We also love using OpenAPI for documenting the actual data fields, the request payloads for mutating requests and query parameters for filters etc. However, we found out that it requires lots of boilerplate for describing the _links object, and especially the _embedded resources.

Is anyone out there using either HAL or json:api, or a similar approach with OpenAPI? And if so, are you interested in either abstracting OpenAPI to natively support these concepts, or perhaps in a separate specification format designed for this type of APIs? Right now I am working on a example document, inspired by OpenAPI, of how such a specification might look like, focusing on HAL support for now.

[handrews]

If you're using OpenAPI 3.1, one thing that might help is $dynamicRef, which can be used to model template data structures.

In general, OpenAPI is more of a design-time tool, while hypermedia is primarily runtime. From the point of view of supporting something like HAL, that seems mostly about making sure that there are good Schema Object patterns to support it.

[handrews]

While it does not help with HAL, note that the newly-released OAS v3.2 has much-improved support for modeling Link headers using application/linkset and/or application/linkset+json and their RFC-defined mapping to individual HTTP Link headers.