Design document on the hydrus workflow

[Mec-iS]

As hydrus define a precise workflow like:

1. the API designer write a SWAGGER/OpenAPI JSON document that describes his/her API (yet to be implemented, hopefully this year. Please consider submitting an application for this)
2. hydrus parser will parse this JSON into a HYDRA API documentation (example here)
3. hydrus deploys the Web server byt parsing the outcome at 2.
4. hydrus serves the API
5. HYDRA-aware generic clients can use the API

We need an extensive document that improve the current WIKI by adding a detailed description of this workflow, with references to RDF codebase and Hydra draft.

References:

• URSA

[vddesai1871]

@Mec-iS I think we already have good documentation of step 2,3 and 4. I think beginners are feeling overwhelmed by HYDRA and JSON-LD specification and skipping or skimming it. And we do not have step 1 implemented yet so I suggest until it's implemented we can have something similar to https://www.hydra-cg.com/spec/latest/core/#using-hydra . Here Marcus is using his issue tracker to illustrate how to write HYDRA API Documentation with JSON-LD. We can have somewhat same document but using drone-flock's documentation as an example (reference). As everything is based on HYDRA it will give beginners a great start and there will be less trivial questions related to Hydra in the chat room. But at last, it will be the same thing Marcus is illustrating so it will involve huge duplication of his work. If you think it's a good idea I can start working on it. @chrizandr @xadahiya views or suggestions?

[Mec-iS]

It is a good idea to have the same documentation but for our example.

I would move this in https://github.com/HTTP-APIs/hydra-ecosystem-wiki and leave this repository for automatically generated documentation from docstrings in the code.

You can create a PR on https://github.com/HTTP-APIs/hydra-ecosystem-wiki to add a Example.md.

[Mec-iS]

Moved to https://github.com/HTTP-APIs/hydra-ecosystem-wiki/issues/16