This contains my notes about designing hypermedia APIs.
Currently the notes are very brief and mostly this is a list of pre-defined formats and specs that can make up an API design.
See RESTful Web APIs for a thorough description of the design process.
- A Web API Design Methodology (article)
- API Design Methodology (presentation video)
- Linking and forms to advertise possible next states (requests)
- Reference data resources where helpful in making next-requests
- Clearly define link relations
- Clearly identify and describe profiles/message-types
Provide hypermedia factors and leave room to layer on application-specific semantics.
- UBER
- HAL
- Siren
- Mason
- JSON-LD: JSON for Linking Data
- Hydra: Hypermedia-Driven Web APIs
- JSON API
- Home Documents for HTTP APIs
- XLink
- XForms
- HAL Forms
- RDF
Types that fully define specific applications. They may still make good base types for other applications that further specialize what they define.
- The Atom Publishing Protocol
- The Atom Syndication Format
- Collection+JSON
- JSON Patch
- OData
- OpenSearch
- Problem Details for HTTP APIs
- Status Documents for HTTP Resources
- Operational Status
- Health checks?
- ALPS
- Hyperdescribe
- JSON Schema
- RDF Schema
- Open API Initiative
These usually generate some combination of documentation, server, and client. This is not the same thing as message-type descriptions and profiles, as these are meant to describe those things on specific trees of URLs. This usually (always) means a specific server or implementation.
I find opinionated API frameworks to be detrimental. They never or rarely make clients and servers equals in the resulting services. It probably takes modelling (see above) to do this and from there a server framework could/should be minimal (e.g., sinatra, morepath, spark).
- Web Concepts
- Microservice architecture
- Including patterns and other resources
- H-Factors