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-hollows

URI 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!

Made with Slides.com