Foundations

Generics

Besides 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 to leverage smart clients. hydrus is the server-side tool that allows REST data to be published as Hydra-aware data. A Hydra network is made up of one or more hydrus instances that receives requests from Hydra smart clients (or agents, see hydra-python-agent repository). The interaction of hydrus and Hydra smart clients is how the 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). RDF is widely known as the technology which makes the Semantic Web possible by representing 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 more detailed explanation of triples, you can read this document.

Hydra

Hydra is a framework that enables REST APIs 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 its virtualization and isolation technology (see Usage). Other tools, such 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 an easier and more efficient creation of hypermedia-driven REST APIs. hydrus utilises the power of Linked Data to create a powerful REST server to serve data. hydrus uses the Hydra(W3C) standard-to-be for creation and documentation of data servers.

Hydra smart client (hydra-python-agent) is a Python implementation of a client based on the Hydra Community Group specifications and reference implementation Heracles.ts. It can navigate a network of hydrus servers autonomously by reading their API documentation. It is a generic client because it can query and retrieve data from any, Hydra-aware or not, server (such as hydrus or any other Web server).

What makes the difference

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

These points highlight all the advantages mentioned in previous paragraphs. Finally, Linked Data is, by Berners-Lee’s design, a 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 few 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:

Other than this, there are also various Python packages that hydrus uses. A list of these packages can be found in the requirements.txt file.

The Hydra agent is a fork and rebuilding of hydra-py, under development here.

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

Demo ————- It is advised to use docker-compose to run the demo server. See README here.

Otherwise, to run a demo for hydrus using the sample API, do the following:

Clone hydrus:

git clone https://github.com/HTTP-APIs/hydrus

Change directory and switch to the develop branch:

cd hydrus

git checkout -b develop origin/develop

Install requirements and run the main.py script:

pip install -r requirements.txt

python main.py

The demo should be now be running on http://localhost:8080/serverapi/.

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

Usage ————- Head over to the Usage page of the wiki to understand how hydrus works and how to use it.

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