What if API clients could explore and understand resources at runtime? Instead of being hardcoded against specific versions of specific APIs, they’d be able to identify accessible data and functionality as they progress through an API, taking further action based on user input, simple algorithms, or even artificial intelligence.

This is exactly what hypermedia APIs aim to achieve — and Hydra is one of few standardized frameworks that describes how these APIs and their corresponding clients should be built. In this article, we’ll look at the benefits of using a framework like Hydra, its components, and some handy examples of how it works.

What Is Hydra?

Hydra is a vocabulary that seeks to simplify the development and consumption of hypermedia-driven web APIs. It’s one answer to the infamous constraint of RESTful API design, Hypermedia as the Engine of Application State, that distinguishes true REST APIs from their REST-like counterparts.

The fourth and final constraint of uniform interface [in RESTful API design] is that application state should be expressed dynamically through hypermedia (known in short as HATEOAS). This means that in addition to returning a representation of the resource in question, a request should also be met by instructions on how to further interact with the resource or API as a whole.

In particular, upon accessing a resource, the client should be provided with information as to what actions can be performed on that resource. These actions should be accompanied by hyperlink references to relevant URIs.

What Problem Does Hydra Solve?

The promises of hypermedia web APIs are many: dynamic explorability, inline documentation, and no more hardcoded resource URIs, among others. In practice, though, hypermedia APIs have seen slow adoption. One reason for this is that there is no standardized framework for recognizing or consuming hypermedia controls. As a result, clients still have to be hardcoded against the hypermedia implementations used in specific APIs — which begs the question, why bother at all?

Hydra aims to address this issue by providing a common vocabulary for concepts frequently seen in web APIs.

Building Blocks of Hydra

In reality, Hydra consists of two key parts. There’s the all-important vocabulary mentioned above — known as the Hydra Core Vocabulary — but there’s also a format for referencing linked data (usually JSON-LD), also known as an RDF serialization format.

JSON-LD

JSON-LD is a W3C standard that defines how to reference linked data in JSON, making it an example of an RDF — or Resource Description Framework — serialization format. It’s fully compatible with JSON, which is to say that it adds functionality without affecting the existing behavior of JSON-based applications or tooling.

One of the major ideas in any RDF serialization format — JSON-LD included — is that values are mapped to standardized formats (per a common vocabulary like schema.org) instead of arbitrary keys. Thus, as long as the consumer is familiar with the vocabulary being used, they can independently determine the meaning of a key-value pair without the need for external documentation.

Hydra Core Vocabulary

Hydra’s pièce de résistance is, of course, the Hydra Core Vocabulary itself. While JSON-LD makes it possible to provide hypermedia affordances (read: links to other resources) in a standardized fashion, the Hydra Core Vocabulary can be used to describe them. The Operation resource identifies operations that can be performed on an affordance, while the method property defines what HTTP method should be used for that operation.

The Hydra Core Vocabulary also provides machine-readable “documentation” functionality. For instance, it specifies the entrypoint for the API, as well as supported classes and possible statuses.

Example

For an in-depth example of Hydra in action, look no further than Tomasz Pluskiewicz’s presentation Bringing Hypermedia to the Masses at the 2019 Platform Summit. He demonstrates a Single-Page Application that dynamically renders a collection of resources — as well as the resources themselves — based on JSON-LD and Hydra properties.

His prototype application, Wikibus.org, lists various artifacts (such as brochures) relating to public transport. On the collection page for brochures, the application renders individual brochure items based on schema:title and schema:image properties specified by JSON-LD.

In a similar fashion, the application renders individual item pages autonomously, based on the schema:image and other properties specified for the object. For instance:

{
  "@context": "https://wikibus-sources.herokuapp.com/_contexts/Brochure",
  "title": "Ernst Auwaerter Clubbus Mediano",
  "wishlistItem": null,
  "@type": [
    "https://wikibus.org/ontology#Source",
    "https://wikibus.org/ontology#Brochure"
  ],
  "@id": "https://sources.wikibus.org/brochure/1182",
  "languages": [
    "langIso:de"
  ],
  "pages": 2,
  "images": {
...
  },
  "content": {
    "@id": "https://sources.wikibus.org/brochure/1182/file",
    "name": "Download PDF",
    "encodingFormat": "application/pdf",
    "contentSize": "7.51 MB",
    "contentUrl": "https://wikibus.blob.core.windows.net/sources1182/EA Clubbus Mediano.pdf",
    "@type": "https://schema.org/MediaObject"
  },
  "contributor": {
    "@id": "https://users.wikibus.org/user/google-oauth2|117957693005245427833"
  }
}

…becomes:

If you’re still not convinced that Hydra is adding any value here, consider this: you could switch public transport brochures with any other resource for an equally rich experience. Since the application’s pages are rendered at runtime — based on properties attached to the resource — little additional code would be needed.

Not to mention, Tomasz’s application is more than read-only! Looking closer at the code, you can see that Hydra is used to annotate various operations with schema.org actions, like CreateAction, UpdateAction, DeleteAction, and TransferAction, providing a machine-readable reference for smart clients.

Final Thoughts

There’s still plenty of work to be done before we can expect hypermedia APIs to achieve widespread adoption. Frameworks like Hydra standardize the consumption of linked data and hypermedia affordances, proving a crucial first step in the development of APIs where resources and operations are discovered at runtime.