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 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 receive 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:

  • on hydrus, a REST interface
  • on hydrus, a Hydra-powered server, with the possibilities of being self-deployable and accepting on-the-fly configuration changes
  • on the smart client, a Hydra-powered generic client which can connect to any Hydra-based APIs without hard-coding its behaviour

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 other frameworks, parsers/translators to other standards, are in the same ecosystem.

hydrus is a set of Python-based tools for 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:

  • a 100% Semantic Web tool as requested by W3C;
  • directly interoperable with any existing RDF/OWL repository (have a look);
  • easily parsable into less fluent API documentation standards. As RDF is semantically highly descriptive, it is much easier to parse documents into a less rich standard flawlessly. While the opposite, such as parsing an OpenAPI document to make its API interoperable with existing Semantic repositories, can take a long time.

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:

  • A generic server that can serve the required data and metadata (in the form of API documentation) to a client over HTTP.
  • A Web interface that interacts with the server or infrastructure through the client using Natural Language which is processed machine consumable language. (under development)

Every Hydra smart client instance provides:

  • A client that can understand Hydra vocabulary and interact autonomously with a Hydra-supporting server via basic CRUD operations on data. The contributors are actively developing a fork of hydra-py to create a generic Hydra Agent.

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

  • Flask, a Python based micro-framework for handling server requests and responses.
  • JSON-LD as the prefered data format.
  • Hydra as the API standard.
  • SQLAlchemy as the backend database ORM for storage and querying operations.

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 hydrus:

pip install -r requirements.txt

python3 setup.py install

Run the server using:

hydrus serve

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.