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.

[handrews]

@someniatko I think the closest thing to a real answer to your question here is $dynamicRef and $dynamicAnchor. These keywords let you define what is essentially a template schema, where you would have one schema for the JSON HAL container structure, and one or more $dynamicRefs for the contents of the container.

Using $dynamicRef is a bit complex, and not all tools that claim to support 3.1 support it fully, but here is a blog post on how to use it: https://json-schema.org/blog/posts/dynamicref-and-generics

There are some challenges to work out with this approach, particularly given that _embedded can embed a variety of resources in arbitrary order. That means you can't simply have $dynamicRef: "#resource" everywhere as it's only dynamic in the sense that it will dynamically resolve to one thing per schema evaluation at runtime. In other words, it works well modeling generics like List<Foo>, but not for a List of arbitrary things.

I'm writing this idea here anyway as there might be a way to get it to work. But don't worry if you don't quite see it from my description here- I don't either!

In 3.1.1 and 3.2, we have called out this use case to encourage better support for $dynamicRef. Initially, I think it was perceived as an obscure feature for supporting the JSON Schema metaschemas, but it actually solves very common use cases such as this one that are not hard to reason about once you realize they correspond to common programming concepts (templates/generics).