This document introduces HYDRA, a lightweight vocabulary that allows the creation of hypermedia-driven web APIs. HYDRA extends JSON-LD to provide semantics that enable servers to advertise valid state transitions to clients. This allows generic clients to understand operations on APIs and navigate through them using hyperlinks. HYDRA aims to address issues with existing RESTful APIs, such as clients needing to be re-written when APIs change, by making APIs self-descriptive through linked data.

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

10. 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"}

11. 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 ?

12. 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

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

14. 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"}}]

15. 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"}}]

16. 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 !

17. Problem
But… our API is not connected !

18. 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"}}

19. 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.

20. HYDRA

21. 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:

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

23. 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" }
},
...

24. Hydra core
vocabulary

25. 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 !

26. Endless… possibilities...

27. Advanced Concepts

28. 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

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

30. 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

31. Current problems with Hydra

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

33. Questions ? Comments ?

34. 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-

35. 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

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