Workflow tutorial #3
Conversation
|
can we use a .webp image instead of .png 🤔 |
|
We can add hyperlinks to corresponding Repos in the following places.
|
| ## Familiarising with Hydra | ||
|
|
||
| The [specification](http://www.hydra-cg.com/spec/latest/core/) defines Hydra as: | ||
|
|
||
| > a lightweight vocabulary to create hypermedia-driven Web APIs. By specifying a number of concepts commonly used in Web APIs it enables the creation of generic API clients. | ||
|
|
||
| Hydra enables a server to advertise valid state transitions in a machine processable way. The information can be changed or modified at a runtime which the agents can understand and adept. The agents which can comprehend these changes are referred to as smart clients. | ||
|
|
||
| The smart client looks for the API Documentation(APIDoc) in the Link header, extracts the entry point to find different routes and then the supported operations and properties for each route on the runtime. These concepts are formalised by the hydra vocabulary. | ||
|
|
||
| ## Linked Data | ||
|
|
||
| [Tim Berners Lee defines](https://www.w3.org/DesignIssues/LinkedData.html) Linked data as: | ||
|
|
||
| > The Semantic Web isn't just about putting data on the web. It is about making links, so that a person or machine can explore the web of data. With linked data, when you have some of it, you can find other, related, data. | ||
|
|
||
| There are three rules that the linked data should follow: | ||
|
|
||
| 1. Use URI for names of things | ||
| 2. Use HTTP URIs so that people can look up those names. | ||
| 3. When someone looks up a URI, provide useful information, using the standards. | ||
| 4. Include links to other URIs. so that they can discover more things. | ||
|
|
||
| With Linked data it becomes easy to integrate different datasets together to achieve different goals. One of the common examples of Linked data dataset is [DBPedia](https://wiki.dbpedia.org/)(the dataset of wikipedia in Linked data format). | ||
|
|
||
| ## JSON-LD | ||
|
|
||
| [JSON-LD](https://json-ld.org/) is a JSON based format to serialise linked data. It annotates the elements of the response and structures the data which helps to disambiguate different data and helps machines better understand the data. | ||
| For example, any human can comprehend that the following response contains data about the name Hydra Ecosystem and contains the url of home page. But machines cannot make any sense from the following data. | ||
|
|
||
| ```json | ||
| { | ||
| "name": "Hydra Ecosystem", | ||
| "homepage": "https://hydraecosystem.org/" | ||
| } | ||
| ``` | ||
|
|
||
| To resolve this, one can use unambiguous identifiers for the name and URL and specify that if the value is an IRI or a string literal. JSON-LD can be used to achieve this by using a popular schema.org vocabulary: | ||
|
|
||
| ```json | ||
| { | ||
| "http://schema.org/name": "Hydra Ecosystem", | ||
| "http://schema.org/url": { | ||
| "@id": "https://hydraecosystem.org/" | ||
| ↑ The '@id' keyword means 'This value is an identifier that is an IRI | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Web APIs | ||
|
|
||
| A Web API is an application programming interface for either a web server or a web browser. One can get the data without bothering about the implementation details. For example to get the weather information of a place, one need not to bother about how the weather is measured. A request to the URL of the API returns with the weather information. | ||
|
|
||
| <div id="main"> | ||
| After going through this document, you should be able to understand the general workflow followed to create and use APIs using the tools of the Hydra Ecosystem. Though the workflow might be different for few use cases, this document tries to cover the general workflow that can satisfy most of the use cases. | ||
| </div> | ||
|
|
||
| To design web APIs using the tools of this ecosystem, follow three simple steps. | ||
|
|
||
| 1. Define the API in JSON-LD format as API Documentation | ||
| 2. Pass this API Documentation to the `hydrus` server | ||
| 3. Use Smart clients(`hydra-python-agent`) to consume APIs served by the `hydrus`. | ||
|
|
There was a problem hiding this comment.
Hmm, when we are keeping the heading of this article is General Workflow, I think the reader should directly get access to the workflow without first getting interrupted by having to go through the related terminologies.
I understand that these terminologies are very important to understand the workflow so how about we probably move all these to another page(which has only terminologies/glossary) which we can hyperlink here?
There was a problem hiding this comment.
The very first paragraph contains the note with a link to the main content, if they are familiar with these, they can jump directly there. That being said, I was not convinced of the idea to direct people to go through a glossary first. I think that will be a little overwhelming. Better to wait to see what other reviewers think about this!
|
|
||
| Hydrus can be used a Command Line Interface(CLI) and as a python package. | ||
|
|
||
| ## 3. Using smart Clients to consume APIs |
There was a problem hiding this comment.
Just a minor nitpick, I think we should change Clients to clients.
|
Overall, a very good article @priyanshunayan! 👍 |
|
Made a new workflow diagram. Editable link, also availble if you need to modify anything. @priyanshunayan We can use this as reference for the text |
|
@chrizandr This is a wonderful illustration. Much Much better than what I had put. This made me understand the whole workflow document at a glance! Just like hydra-python-agent, hydrus can also be used as a python package, as well as a CLI, did you hide that purposefully? I can add that if you missed it? |
|
hydrus CLI is just to start the server right? I don't think that would be needed. We're not using that to access data. It would be great if we could add something to show crud operations. Right now it just looks like client is consuming data from hydrus but nothing shows that client can also add data. |
|
in perspective everything useful for the developer should be available via CLU, examples: bulk-load data from common format, delete instances and relationships, etc. obviously these operations should use the REST API to apply the changre |
|
I have an idea to create a separate repo with Movie API implementation in which we can show both adding and retrieving data.
|
There was a problem hiding this comment.
It is important to have uniform treatment for names, as engineers use standard names to point to precise concepts and objects:
- json is not JSON (as it is an acronym)
- Linked Data (W3C) is a different object than just "linked data" (general)
- writing "hydra" is an error as the official standard specification name is Hydra
- etc
I know this is coming from old contributions and it is time to address this non-conformity.
If you have any doubt about the context and which name to use, please ask.
|
|
||
| > a lightweight vocabulary to create hypermedia-driven Web APIs. By specifying a number of concepts commonly used in Web APIs it enables the creation of generic API clients. | ||
|
|
||
| Hydra enables a server to advertise valid state transitions in a machine processable way. The information can be changed or modified at a runtime which the agents can understand and adept. The agents which can comprehend these changes are referred to as smart clients. |
There was a problem hiding this comment.
add a note like: "In Hydra Ecosystem the smart client is called 'agent'", with links to the doc and repo for hydra-python-agent
|
|
||
| [Tim Berners Lee defines](https://www.w3.org/DesignIssues/LinkedData.html) Linked data as: | ||
|
|
||
| > The Semantic Web isn't just about putting data on the web. It is about making links, so that a person or machine can explore the web of data. With linked data, when you have some of it, you can find other, related, data. |
There was a problem hiding this comment.
here again we can get confused:
- Linked Data (uppercase) is the official W3C definition for, with attached standards (RDFs etc.)
- linked data is just any data that is interrelated ("connected" or providing references)
please double-check that the instances in the documentation use the right specification for the context used
|
There is a small typo
|
|
I tried to make this article as accessible as possible for everyone. But I found myself using the terms
json-ld,web APIs,hydraagain and again. I did not want to overwhelm beginners with the comprehensive guides about these terms, so I included bare minimum information about this technology, just enough to follow along with the tutorial. Please let me know if this needs addtions/subtraction.[EDIT] - Page to review: https://deploy-preview-3--hydra-docs.netlify.app/src-content-tutorial-workflow