Foundations: Hydra Ecosystem


Beside all the other tools in the ecosystem, hydrus (lowercase) is the basic module from which API designers/engineers/developers can build up their own automated infrastructure that leverages smart clients. hydrus is the server-side tool that allows REST data to be published as Hydra-aware data. An Hydra network is made up of one or more hydrus instances that can receive requests from Hydra smart clients (or agents, see hydra-python-agent repository). The interaction of hydrus and Hydra smart clients is how Hydra ecosystem realizes the Client-Server pattern.

hydrus provides a full-stack architecture that makes it the basic building block for a machine that is a node in a wider network of Web APIs. Generic components of the network are:

RDF and Linked Data

Hydra is an extension of W3C’s Resource Description Framework. RDF is widely known as the technology which makes possible the Semantic Web by allowing the representation of data as Linked Data. RDF is a W3C standard that allows the representation of Knowledge in specific Domain as Knowledge Graphs. Quanta of information are represented as “triples”: statements that relate a subject to an object by a predicate. Triples can be stored in different formats, the format used in Hydra and hydrus is JSON-LD. For a little more detailed explanation of triples you can read this document.


Hydra is a framework to enable REST API to be described semantically using RDF. It is based on JSON-LD and proposed as W3C draft.

hydrus (lowercase) is the flagship server in the ecosystem. It is a Flask server meant to build and deploy Hydra-based Web APIs in a straightforward and effective way. It uses Docker as virtualization and isolation technology (see Usage). Other tools, as dedicated clients for testing, instances running with others frameworks, parsers/translators to other standards, are in the same ecosystem.

hydrus is a set of Python based tools for easier and efficient creation of Hypermedia driven REST-APIs. hydrus utilises the power of Linked Data to create a powerful REST APIs to serve data. hydrus uses the Hydra(W3C) standard for creation and documentation of its APIs.

Hydra smart client (hydra-python-agent) is a Python implementation of a client based on the Hydra Community Group specifications. It can navigate a network of hydrus servers autonomously by reading their API documentation. It is a generic client in the sense that can query and retrieve data from any Hydra-aware server (like hydrus).

What makes the difference

How does Hydra compare to other API documentation standards? Hydra is generally better rooted than other projects (i.e. OpenAPI) as it leverages the experience of now thirty-years-old Linked Data ecosystem. This makes Hydra:

These points add up to all the advantages mentioned in previous paragraphs. Finally Linked Data is, by Berners-Lee’s design, the tool to distribute data on the Web; Hydra adheres to this path of evolution to keep the Web open as wished by its creators and developers during the last decades.

Table of contents

Features ————- Every hydrus instance provides the following tools:

Every Hydra smart client instance provides:

Requirements ————- The hydrus system is built over the following standards and tools:

The smart client system is a fork of hydra-py, named python-hydra-agent, under development here.

NOTE: hydrus and Hydra Agent supports only Python 3.5 and above

Demo ————- To run a demo for hydrus using the sample API, just do the following:

Clone hydrus:

git clone

Change directory and switch to the develop branch:

cd hydrus

git checkout -b develop origin/develop

Install requirements and run the script:

pip install -r requirements.txt


The demo should be up and running on http://localhost:8080/serverapi/

Workflow ————- For a generic overview of the Development workflow, head over to Workflow page.

Usage ————- To understand how to use hydrus and how things work, head over to the Usage page of the wiki.

Design ————- Head over to the Design page to understand the design principles and use cases of hydrus.