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 python-hydra-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:
- 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, a generic client that can connect to any Hydra-based APIs without hard-coding its behaviour
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 it's APIs.
Hydra smart client (python-hydra-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).
Every hydrus instance provides the following tools:
- A generic server that can serve required data and metadata (in the form of API documentation) to a client over HTTP.
- A Web interface that allows users to use the client to interact with the server/infrastructure using Natural Language which is processed machine consumable language. (under developement)
Every Hydra smart client instance provides:
- A client (
hydra-py) 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 ofhydra-pyfor the sake of creating a generic Hydra Agent.
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 connector for storage and related operations. Apart from these, there are also various Python packages that hydrus leverages. A list of all these packages can be found in the requirements.txt file.
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
To run a demo for hydrus using the sample API, just do the following:
Clone hydrus:
git clone https://github.com/HTTP-APIs/hydrusChange directory and switch to the develop branch:
cd hydrus
git checkout -b develop origin/developInstall requirements and run the main.py script:
pip install -r requirements.txt
python main.pyThe demo should be up and running on http://localhost:8080/serverapi/
For a generic overview of the Development workflow, head over to Workflow page.
To understand how to use hydrus and how things work, head over to the Usage page of the wiki.
Head over to the Design page to understand the design principles and use cases of hydrus.