HAL/HATEOAS
AGENDA
- Back to the roots.
- now HATEOAS/HAL.
- But Why?
- Ok, so How?
- mmm, Conclusions...
Back to the roots
REST 101
REST
Representational state transfer
definition:
is an architectural style defined to help create and organize distributed systems
Again!
- Rest is an style.
- Not a guideline.
- Not a standard
What "full" REST promise
- Performance.
- Scalability of component interaction.
- Simplicity of interface.
- Modifiability of components.
- Portability.
- Reliability.
- Visibility.
How can i have such Awesomeness?
REST Constraints
Constraints
- Client/Server.
- Stateless.
- Cacheable.
- Layered System.
- Code-on-demand.
- Uniform Interface.
Client/Server
Key goal: Separation of concerns
Stateless
Key goal: Visibility/Scalability/Reliability.
Hint: There is a tradeoff
TRAFFIC
Cacheable
Key goal: Perfomance
CACHEEEE!
Layered System
Key goal: Simplicity.
CACHEEEE!
Tradeoff ?
Latency on small systems
Code-on-Demand
Key goal: Manteinability.
CACHEEEE!
Optional
Uniform Interface
Key goal: Simplicity/Consistency.
CACHEEEE!
Uniform Interface: Rules
- Indentification of resources.
- Manipulation through representation.
- Self-descriptive messages.
- HATEOAS!!!
Uniform Interface: Resources
Resource Structure Description:
- Representations.
- Identifier.
- Metadata.
- Control data.
Resource: Main building block. Name it and its a resource.
Uniform Interface: Representations
A way to communicate.
{
"date": "2014-10-25",
"max_temp": 25.5,
"min_temp": 10.0,
"temp_unit": "C",
"humidity_percentage": 75.0,
"cloud_coverage": "low"
} <?xml version='1.0' encoding='UTF-8' ?>
<root>
<temp_unit value="C" />
<humidity_percentage value="75.0" />
<cloud_coverage value="low" />
<date value="2014-10-25" />
<min_temp value="10.0" />
<max_temp value="25.5" />
</root> 2014-10-25|25.5|10.0|C|75.0|low Representation could be requested: Content Negotiation/ extension
Uniform Interface: Resource Identifier
Also known as: URI
full URI
GET /api/v1/books /j-k-rowling/harry-potter-and-the-deathly-hollowsURI should always return the same resource.
GET /api/v1/books/last Not very "restful":
Uniform Interface: Actions
Manipulation through Representation:
GET
POST
PUT
DELETE
OPTIONS
Respect Status Code!!
HATEOAS!!
Hypermedia as the Engine of Application State
HATEOAS: metadata
Every Resources have METADATA
Metadata are just LINKS!
Basic Root endpoint: GET /api/v1
{
"metadata": {
"links": [
"books": {
"uri": "/books",
"content-type": "application/json"
},
"authors": {
"uri": "/authors",
"content-type": "application/json"
}
]
}
} HATEOAS: metadata
Powered Root endpoint: GET /api/v1
{
"resources": [
{
"title": "Harry Potter and the Half Blood prince",
"description": "......",
"author": {
"name": "J.K.Rowling",
"metadata": {
"links": {
"data": {
"uri": "/authors/j-k-rowling",
"content-type": "application/json"
},
"books": {
"uri": "/authors/j-k-rowling/books",
"content-type": "application/json"
}
}
}
}
}
... metadata structure is an Architecture decition
HAL: Hypertext Application Language
Define a Representation with Resources links and state.
{
"_embedded": [
{
"title": "Harry Potter and the Half Blood prince",
"description": "......",
"copies": 10,
"_embedded": {
"author": {
"name": "J.K.Rowling",
"_links": {
"self": {
"href": "/authors/j-k-rowling",
"type": "application/json+hal"
},
"books": {
"href": "/authors/j-k-rowling/books",
"type": "application/json+hal"
}
}
}
}
}
]
}But Why?
-
Discoverability.
-
Interaction.
-
Inline Documentation.
-
Clear Communication.
OK, so how?
-
Depends on the platform.
- Build by scratch.
- Use a library.
mmm, conclusions
-
A lot of overhead.
-
Enduser have no benefits so ever.
-
Live API documentation (Swagger) could help in most cases.
Preguntas?
Danke schön!
HAL/HATEOAS
By Maximiliano “Massi” Cespedes