Hypermedia APIs
Related
Everything as a Resource
- Data model as a resource: Describing the data model as a resource could help build forms for entering data or interactive user interfaces. One vocabulary to assist here is the SHACL Shapes Constraint Language for describing graph data structures.
- Hypermedia as a resource: The API itself can be described as a resource too. One way to do this is using Hydra, a vocabulary for describing APIs with RDF. This sort of self-documentation is similar to OpenAPI but could make the API discoverable at runtime.
- Access control as a resource: The Basic Access Control ontology is another shared vocabulary for describing access control that was proposed by none other than Tim Berners-Lee.
Solutions
Comparisons
Hypermedia APIs vs. Data APIs
Hypermedia APIs:
- Will be trivially REST-ful, since they are simply what Roy Fielding was describing.
- Should be driven by the needs of the underlying hypermedia application
- May change dramatically without versioning information, because hypermedia utilizes self describing messages
- Should be passed directly to humans, to maximize the flexibility of the system
Data APIs, on the other hand:
- Will not benefit dramatically from REST-fulness, beyond perhaps Level 2 of the Richardson Maturity Model
- Should strive for both regularity and expressiveness due to the arbitrary data needs of consumers
- Should be versioned and should be very stable within a particular version of the API
- Should be consumed by code, processed and then potentially presented to a human
Can you have both? Of course! See https://hypermedia.systems/json-data-apis/
References
- https://nordicapis.com/exploring-the-hidden-powers-of-hypermedia/
- https://htmx.org/essays/hypermedia-apis-vs-data-apis/
- https://sookocheff.com/post/api/on-choosing-a-hypermedia-format/
- https://medium.com/@cheron.antoine/which-technologies-should-you-use-to-build-hypermedia-apis-5047f2964cc4
Backlinks