Hypermedia APIs

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


Backlinks