Embracing Change with REST

Embracing Change with REST Kyle Fuller

Representational State Transfer

What is REST?

Roy Fielding

“Anticipating change is one of the central themes of REST”

"Move fast and break things" Mark Zuckerberg, Facebook

"Each version will remain for at least 2 years from
release." Facebook

Move Fast, Break Nothing

REST is not... 4 CRUD 4 Pretty URLs 4 JSON
4 HTTP Verbs 4 Routing

It’s not about exposing your database

But... we design apps this way

Actually, We Don't

We design implementations this way

Todo 4 id 4 title 4 status

Designing API by exposing implementation details

We could design via states

How do we Transfer State from Server to Client?

We transfer Representations of State

Hence Representational State Transfer

How do we transfer state transitions?

HATEOAS

HATEOAS Hypermedia as the Engine of Application State

Relations

Transitions

"HATEOAS" is a REST constraint.

Not an option. Not an ideal. Hypermedia is a constraint.

As in, you either do it or you aren’t doing
REST.

GET http://polls.com/ <html> <body> <h1>Things you can do</h1> <ul> <li><a
href="/questions/new" rel="create">Make a new question</a></li> </ul> </body> </html>

GET http://polls.com/ <html> <body> <h1>Things you can do</h1> <ul> <li><a
href="/polls/new" rel="create">Make a new question</a></li> </ul> </body> </html>

Creating a question the bad way 4 Construct a 'new
question' URL 4 Submit a form given our pre-existing knowledge of how it may look 4 Visit the page (it may or may not work)

with hypermedia 4 We’re offered to create a question 4
Fill in the form it gives you 4 Submit the form

Exactly how you browse the web

Clients can have the same benefits by doing this too

Questions 4 create 4 list

Question 4 delete 4 choices

Choice 4 vote

One Does Not Simply Use JSON

Hypermedia Formats 4 HAL (application/hal+json) 4 Siren (application/vnd.siren+json)

Siren Link { "links": [ { "rel": ["next"], "href": "/questions?page=2"
} ] }

Siren Link { "links": [ { "rel": ["choice"], "href": "/questions/1/choices/1"
} ] }

Siren Link { "entities": [ { "links" { { "rel":
["self"], "href": "/questions/1/choices/1" } }, "rel": ["choices"], "properties": {"choice": "Swift", "votes": 22} } ] }

Siren Link { "entities": [ { "rel": ["choices"], "properties": {"choice":
"Swift", "votes": 22}, "actions": [ { "href": "/questions/1/choices/1", "name": "vote", "method": "POST" } ] } ] }

Siren Action { "actions": { "create": { "href": "/questions", "method":
"POST", "fields": [ { "name": "question" }, { "name": "choices" } ] } } }

"POST", "fields": [ { "name": "question" }, { "name": "choices" } ], "type": "application/x-www-form-urlencoded" } } }

"POST", "fields": [ { "name": "question" }, { "name": "choices" } ], "type": "application/json" } } }

{ "actions": { "create": { "href": "/questions", "method": "POST", "fields":
[ { "name": "question" }, { "name": "choices" } ], "type": "application/json" } } }

Ability to change implementation details

Ability to change implementation details 4 Change URIs of resources
(/polls/{id} -> / questions/{slug})

(/polls/{id} -> / questions/{slug}) 4 Change HTTP methods (PUT -> PATCH)

(/polls/{id} -> / questions/{slug}) 4 Change HTTP methods (PUT -> PATCH) 4 Change the content-type

(/polls/{id} -> / questions/{slug}) 4 Change HTTP methods (PUT -> PATCH) 4 Change the content-type 4 Change fields used in forms

Teach Clients Semantic meaning of the Domain

Don’t hard-code implementation details

Representor https://github.com/the-hypermedia-project/representor-swift

Using a transition if let transition = representor.transitions["create"] { }

Using a transition if let transition = representor.transitions["create"] { }
else { // Gracefully handle the lack of this transition }

Using a transition if let transition = representor.transitions["create"] { transition.attributes
}

Using a transition if let transition = representor.transitions["create"] { transition.method
transition.uri transition.suggestedContentType }

Performing a Transition request(transition, attributes:[ "question": "Favourite programming language?", "choices":
[ "Swift", "Python", ] ])

Resources 4 REST APIs must be hypertext driven 4 Representor
4 Roy Fielding on Versioning 4 Polls API 4 rivr rest 4 Solving Fizz Buzz with Hypermedia

Kyle Fuller ! fuller.li/slides ! [email protected]

Embracing Change with REST

Embracing Change with REST

More Decks by Kyle Fuller

Other Decks in Technology

Featured

Transcript