Developing APIs with Hydra: Workflow

A Developer wishing to design and deploy his/her own data services with Hydra, hydrus (the server) and hydra-agent (the client) has to go through a workflow that is defined by multiple steps: from defining the best Hydra/RDF/OpenAPI description of the resources and operations he/she is going to provide, to create the conditions for the services to be deployed by hydrus and for the hydra-agent to access them.

In general, the workflow is made up of these basic steps:

  1. The Developer defines an API description in the shape of an RDF-compliant or Hydra-compliant JSON-LD (Hydra is an RDF vocabulary itself) or in the shape of an OpenAPI data structure (yet to be implemented). Any shape that is supplied it is parsed into an Hydra-compliant JSON-LD that becomes the API documentation (in Hydra slang, the ApiDoc). Every REST resource is identified by an HydraClass.
  2. hydrus toolkit can parse the ApiDoc and define handlers to support the pusblishing of the resources as described by the Developer. It puts in place a system for credentials management to secure the endpoints with Two-factors token authentication. Every HydraClass has its endpoint and HTTP methods and related operations as defined by the documentation. It may be possible in future to deploy every HydraClass in a “database per service” fashion, all the server instances generated by the same ApiDoc share the same hydrus’s RDF graph storage, so to allow access to other instances’ resources in case of hydra:search (query on multiple resources) operations.
  3. hydra-agent reads the ApiDoc via the entrypoint and parses the JSON-LD into an internal representation (RDF graph) that allows the client to proceed to query the endpoints for its searching, storing or retrieving necessities. The internal representation may change on-the-fly or grow depending from the different ApiDoc that the clients reaches. The official Hydra client implementation is Heracles.ts.

In general, an Hydra network is made up by the interaction of the functionalities of an instance of hydra-agent with a self-deployable Hydra-based HTTP server as hydrus. An hydra-agent is an HTTP client with capabilities of translating REST queries from-to a graph query language, so to allow efficient navigation of the graph’s internal representation (see this paragraph in Design).

Follow on to Example for a more in depth explanation.