Introduction to Hydra

46 %
54 %
Information about Introduction to Hydra

Published on October 12, 2016

Author: AlejandroInestal

Source: slideshare.net

1. Introduction to HYDRA HYpermedia DRiven APIs Alejandro Inestal alejandro.inestal@unrulygroup.com

2. The Briefing Where are we ? Where do we want to be?

3. What is REST ? Representational state transfer (REST) or RESTful is an architectural style used for web development. Technically, REST consists of a coordinated set of components, connectors, and data elements within a distributed hypermedia system, where the focus is on component roles and a specific set of interactions between data elements

4. Rest purpose Its purpose is to induce Performance Scalability Simplicity Modifiability Visibility Portability Reliability

5. How is REST implemented now ? List of end-points to access resources Set of CRUD operations over HTTP methods Documented outside the API itself

6. What is HYDRA ? Lightweight vocabulary to create hypermedia-driven Web APIs Allows the creation of generic clients Provides a vocabulary which enables a server to advertise valid state transitions to a client It extends JSON-LD

7. Why Hydra ? you don’t want to rewrite your client after changes in the API like New end-point New attributes or parameters New services included in your API … or any other change you don’t want to write a different client for every single API out there

8. The Journey The journey to get a true REST

9. This is considered RESTful now - Users: Collection of users of the TODO application url: http://example.com/api/users - GET: description: Returns all the users in the application response payload: id: string email: string name: string example: [{"id": "1", "email": "foo@bar.com", "name": "foo bar"}, {"id": "2", "email": "wadus@bar.com", "name": "wadus bar"}] - POST: description: Creates a new user in the application request payload: email: string password: string name: string response payload: id: string email: string name: string example: {"id":"4", "email":"new@user.com", "name": "new user"}

10. Problem What are the relations between the resources ? I.e: When a user have ToDo’s, what is the endpoint to access the todo’s ?

11. JSON with hyperlinks example: [{"id": "1", "email": "foo@bar.com", "name": "foo bar", "self_url": "http://example.com/api/users/1", "todos_url":"http://example.com/api/users/1/todo s"}, {"id": "2", "email": "wadus@bar.com", "name": "wadus bar", "self_url":"http://example.com/api/users/2", "todos_url":"http://example.com/api/users/2/todo s"}] - Users: description: Collection of users of the TODO application url: http://example.com/api/users - GET: description: Returns all the users in the application response payload: array: self_url: string id: string email: string name: string todos_url: string

12. Problem How can a generic client understand whether something is an URL or just a string ?

13. Linked data - Users: description: Collection of users of the TODO application url: http://example.com/api/users - GET: description: Returns all the users in the application response payload: array: @id: link self_url: string id: string email: string name: string todos_url: link example: [{"id": "1", "email": "foo@bar.com", "name": "foo bar", "@id": "http://example.com/api/users/1", "todos_url": {"@id": "http://example.com/api/users/1/todos"}}, {"id": "2", "email": "wadus@bar.com", "name": "wadus bar", "@id":"http://example.com/api/users/2" "todos_url": {"@id": "http://example.com/api/users/2/todos"}}]

14. Using URIs: Linked Data on steroids (vocabularies) - Users: description: Collection of users of the TODO application url: http://example.com/api/users - GET: description: Returns all the users in the application response payload: array: @id: link id: string email: string name: string todos_url: link [{"@context":{"@vocab":"http://example.com /api/vocabulary#"}, "id": "1", "email": "foo@bar.com", "name": "foo bar", "@id": "http://example.com/api/users/1", "todos_url": {"@id": "http://example.com/api/users/1/todos"}}, {"id": "2", "email": "wadus@bar.com", "name": "wadus bar", "@id":"http://example.com/api/users/2" "todos_url": {"@id": "http://example.com/api/users/2/todos"}}]

15. RDF graphs and SPARQL Now we have connected graphs (RDF: Resource Description Framework) We can query the graphs using SparQL. The query is able to go through the nodes in the graph. It is also able to query between graphs !

16. Problem But… our API is not connected !

17. Knock knock… aka: entry point - Example API Entry Point: url: http://example.com/api - GET: description: Entry point for the API response payload: @id: link users_url: link example: {"@context":{"@vocab":"http://example.com/api/vocabulary#"}, "@id":"http://example.com/api", "users_url": {"@id":"http://example.com/api/users"}}

18. Problems Our generic client only can go through our API in read mode. JSON- LD doesn’t allow to specify HTTP methods. We need semantics to be able to understand the possible operations on the API.

19. HYDRA

20. Introducing Hydra GET HEAD POST PUT OPTIONS TRACE CONNECT PATCH Hydra allows us to specify allowed operations on the resources This will allow us to describe semantics The hydra operations will be HTTP methods, they are:

21. Describing properties with Hydra "hydra:supportedProperty": [ { "hydra:property": { "@id": "http://example.com/api/vocab#name", "rdfs:range": "xsd:string" }, "readonly": false, "required": false }, …. ]

22. Describing operations with Hydra {"hydra:property": { "@id": "http://example.com/api/vocab#todos", "@type": "hydra:Link", "hydra:supportedOperation": [ { "hydra:method": "GET", "hydra:returns": { "@id": "http://example.com/api/vocab#User" } }, ...

23. Hydra core vocabulary

24. What are the benefits for us? The ability to reach any resource in our API just following links The ability to know all the operations we can do on the API Auto-Descriptive: this API is now containing the documentation itself We can link our API with external API’s or other resources !

25. Endless… possibilities...

26. Advanced Concepts

27. TBox and ABox TBox: Terminological Box https://en.wikipedia.org/wiki/Tbox Conceptualisation associated with a set of facts This is the metadata description of the API e.g: the description of the user end point ABox: Assertion Box https://en.wikipedia.org/wiki/Abox Facts associated with the TBox These are the specific results returned e.g: the specific user returned TBox and Abox can be together in the same document provided by the API or in different documents. Mandatory: TBox always has to be accessible by a client

28. Vocabularies We can create a new vocabulary for each API we create… ...or we can use vocabularies that are already out there.

29. Using known vocabularies (https://lov.okfn.org/dataset/lov/) has several advantages No need to waste time re-inventing the wheel Better compatibility with other APIs Open Vocabularies

30. Current problems with Hydra

31. Current problems with Hydra Not widely used Doesn’t have much libraries yet Still being defined. It may change over time

32. Questions ? Comments ?

33. Resources http://www.markus-lanthaler.com/hydra/ Hydra Console to practice and test http://www.hydra-cg.com/ Official web https://www.hydra-cg.com/spec/latest/core/ Core vocabulary documentation https://github.com/lanthaler/Hydra Hydra vocabulary http://json-ld.org/learn.html JSON-LD resources https://www.w3.org/community/hydra/ Hydra community group https://www.w3.org/community/hydra/wiki/Restbucks_with_Hydra Example https://antoniogarrote.wordpress.com/2016/09/08/from-rpc-to-hypermedia-api-in-

34. More resources https://lov.okfn.org/dataset/lov/ Linked Open Vocabularies http://dublincore.org group about metadata description, vocabularies http://schema.org/ schemas for structured data on the internet

35. Thank you very much ! Further questions: alejandro.inestal@unrulygroup.com Special thanks to Antonio Garrote, who introduced me to this new world !

Add a comment