W3CHydra is an RDF vocabulary for creating hypermedia-driven Web APIs that are self-describing and machine-navigable. It enables API servers to advertise available operations, link structures, and data schemas directly within their responses, allowing generic clients to discover and interact with API capabilities at runtime without relying on external documentation or hardcoded knowledge of endpoint structures.
Background
Traditional Web APIs require developers to read documentation, understand endpoint URLs, and hardcode interaction patterns into clients. This tight coupling between client and server contradicts the architectural principles of the web, where hypermedia (links and forms in HTML) allows browsers to navigate without prior knowledge of a site's structure. Hydra applies this principle to machine-to-machine interactions. Initiated by Markus Lanthaler around 2013, the vocabulary is developed by the Hydra W3C Community Group. The specification remains an unofficial draft and has not advanced to W3C Recommendation status, but it has influenced thinking about hypermedia APIs in the linked data community.
Purpose & Scope
Hydra defines vocabulary terms that allow API responses to describe what actions a client can perform next. Key classes include:
| Class | Purpose |
|---|---|
hydra:ApiDocumentation |
Entry point describing the API's supported classes and operations |
hydra:Collection |
A collection of resources that can be paginated |
hydra:Operation |
An action that can be performed, specifying HTTP method and expected input/output |
hydra:IriTemplate |
A URI template with variable mappings for constructing request URLs |
hydra:Class |
Describes a class of resources and their supported properties and operations |
hydra:PartialCollectionView |
Pagination controls for navigating large collections |
A typical Hydra-enabled API response includes JSON-LD context referencing the Hydra vocabulary, inline operation descriptions indicating what the client can do with the returned resource, and links to related resources and collections. A generic Hydra client can parse these descriptions and present available actions to users or automated agents without prior API-specific programming.
Governance & Maintenance
Hydra is developed by the Hydra W3C Community Group, an open group that collaborates through GitHub and the W3C community group process. The specification is versioned on GitHub and published at the community group's website. Because it has not reached Recommendation status, implementers should be aware that the vocabulary may evolve.
Notable Implementations
Several experimental and production systems have adopted Hydra. The Markus Lanthaler's reference client implementation demonstrates generic API navigation. The vocabulary has been used in conjunction with JSON-LD APIs in academic research projects and in some enterprise linked data platforms. It has also influenced the design of other hypermedia API specifications and the broader discussion around HATEOAS (Hypermedia as the Engine of Application State) in REST API design.
Related Standards
- JSON-LD -- The primary serialization format used with Hydra for embedding API descriptions in responses
- Schema.org -- Provides vocabulary terms that Hydra-enabled APIs often use to describe their data
- OpenAPI -- A non-RDF approach to API description that serves a similar documentation purpose but without runtime hypermedia discovery