Workflow: Developing APIs with Hydra

A Developer wishing to design and deploy his/her 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 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 (see OpenAPI-to-Hydra parser). Any shape that is supplied it is parsed into an Hydra-compliant JSON-LD that becomes the API documentation (in Hydra parlance: the ApiDoc). Every REST resource is identified by an HydraClass.
  2. hydrus toolkit can parse the ApiDoc and define handlers to support the publishing of the resources as described by the Developer; if configured, 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 (a 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 an instance of Hydra agent with one or more instances of 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.