L18 REST API Design

transcript

Lecture L18REST API Design

What is REST? An architectural style

– Representational State Transfer REST is defined in Roy Fielding’s

dissertation from 2000

Adoption of REST

Why REST Scalability Generality Independence Latency Security Encapsulation

HATEOASHypermediaAsTheEngineOfApplicationState

What is REST? Quick and insufficient explanations:

– REST is nothing more than Web Service with the fancy URIs

– REST = CRUD – that is,

POST, GET, PUT, DELETE = Create, Read, Update, Delete

almost, not quite since POST can create

Better understanding REST stands for Representational State

Transfer it is an Architectural Style for distributed hypermedia systems– It has nothing to do with XML, HTTP or the Web– XML is one way to represent resources, but not

the only way

Better understanding HTTP/1.1 was built in a RESTful manner

– The Web is the largest known implementation of a system conforming to the REST architectural style

REST is not CRUD– There are some similarities, but ‘similar’ is far

from ‘same’– In best case CRUD is a subset of REST

Better understanding Representational State Transfer

Client gets information about the data from the SERVER

CLIENT SERVER

RESOURCE DATASESSION DATA

URI REQUEST

RESOURCE

HYPERMEDIA Stateless

Uniform Interface REST is defined by 4

interface constraints: – Identification of resources– Manipulation of resources

through representations– Self-descriptive messages– Hypermedia as the engine of application state

(HATEOAS)

Richardson Maturity Model (RMM) Level 0

– SOAP, XML RPC, POX

– Single URI Level 1

– URI Tunnelling– Many URI, Single

Level 2– Many URIs, Many

verbs– CRUD services

Level 3– Level 2 +

Hypermedia– RESTful Services

Level 0 Everything is packed in XML

– Ignoring all HTTP features– SOAP envelope– Ignores all status codes – 55 codes (including

“418 I’m a tepot”)

Level 1 We understand that if every resource can

be identified by a URI, then we can POST to that URI for some expected result– Many URI, one request method– Still not good enough, as we skip some of the

benefits of the protocol– POST cannot be cached

Level 2 Different verbs or request methods (GET,

PUT, and DELETE) – and use them, as they were intended

Safe IdempotentGET Yes YesPUT No YesDELETE No YesPOST No No

Level 3 HATEOAS – Hypermedia as the engine of

Application State– Don’t hardcode your values, use the

navigational aspect of the web– Hardcoding is easy and fast, but hard to

change – in a distributed world, hard becomes ‘nearly impossible’

– With POJOs we don’t hardcode the memory address, we use pointers

Level 3

Why use the values of the second column if we can agree on the keys for these value – the actions?

Action URIAdd new comment to a blog POST /blog/17/comment/Get all the comments for blog entry number 17

GET /blog/17/comment/

Get user 167671 GET /user/167671Update a user number 167671 PUT /user/167671

Level 3

The response of “get user 167671” will contain keys like “UPDATE” and the value is “http://example.is/user/167671

Action URIAdd new comment to a blog POST /blog/17/comment/Get all the comments for blog entry number 17

GET /blog/17/comment/

Get user 167671 GET /user/167671Update a user number 167671 PUT /user/167671

REST Explained Briefly REST over HTTP leverages HTTP

– Uses HTTP request methods: GET, POST, PUT, DELETE

GET is safe – does not have side effects– Possible to cache client side– 80% or more of the requests are GET

GET, PUT and DELETE are idempotent POST is not idempotent

Resources Nouns, not verbs

– Examples: Account, Group, Customer– Not behavior

Two types– Collection of resources– Instance of a resource

/applications/applications/7828

REST Behavior GET to get resource POST to add resource PUT to update resource DELETE to delete resource HEAD to get header information

Getting

Adding

Updating

GET someservice.com/api/customer/3829

POST someservice.com/api/customer/

REST examples

PUT someservice.com/api/customer/3829

GET On the parent resource: collection

GET /users/789

200 OK{ “users”: { “username”: “olandri”, ... }}

GET On the parent resource, give me a specific

instanceGET /users/789

200 OK{ { “username”: “olandri”, ... }}

POST as Create On the parent resource

POST /users{ “username”: “olandri”, “firstname”: “Ólafur Andri”, “lastname”: “Ragnarsson”}

201 CreatedLocation: https://api.ruber.com/users/789

POST as Update On the parent resource

– Allows partial updates, which is important for complex data type

POST /users/789{ “username”: “olandri”,}

200 OK

Endpoint considerations For internal use, you can use anything

– http://www.foo.com/dev/api/

But if you want others to use– http://api.ruber.com

Versions Two ways

URLhttps://api.ruber.com/v1

Media-TypeApplication/json;application&v=1

JSON JS in JSON is JavaScript XML is also possible JSON is fits well with JavaScript

manipulation Libraries make all this easier Maps well to objects like POJOs Compact format, much better space

complexity than XML

Example{ "firstName": "John", "lastName": "Smith", "isAlive": true, "age": 25, "height_cm": 167.6, "address": { "streetAddress": "21 2nd Street", "city": "New York", "state": "NY", "postalCode": "10021-3100" }, "phoneNumbers": [ { "type": "home", "number": "212 555-1234" }, { "type": "office", "number": "646 555-4567" } ], "children": [], "spouse": null}

Resource Oriented Design Example: School, Student, and Classes in

their normal relationship– schools have zero or more students– schools have zero or more classes– students have zero or more classes– classes have zero or more students

Resource Oriented Designhttp://example.com/lms/schools => list of schoolshttp://example.com/lms/schools/{school} => info about one schoolhttp://example.com/lms/schools/{school}/students => list of studentshttp://example.com/lms/schools/{school}/students/{student} => info on one studenthttp://example.com/lms/schools/{school}/students/{student}/courses => list of courses (as links, not full resources) student is enrolled inhttp://example.com/lms/schools/{school}/courses => list of courseshttp://example.com/lms/schools/{school}/courses/{course} => info on one coursehttp://example.com/lms/schools/{school}/courses/{course}/students => list of students (as links, not full resources) enrolled in course

Resource Oriented Designhttp://www.example.com/lms/students/123

{"ID" : 123,"name": "Name of Student","SSN" : 123456789,"DateOfBirth" : "2001-01-01"

Resource Oriented Designhttp://www.example.com√lms/students/123

{"Classes" : [

{"name" : ”History","link" : " http://www.example.com/classes/117"

"name" : ”New Technology","link" : " http://www.example.com/classes/118"

Level 3{ "id": "98423808305", "from": { "name": "Coca-Cola", "category": "Consumer_products”, "id": "40796308305" }, "name": "A spectacular artwork made solely from used aluminum cans has been unveiled on top of the chalk cliffs of the Sussex coastline to mark the beginning of Recycle Week.", "picture": "http://photos-e.ak.fbcdn.net/hphotos-ak-snc1/hs085.snc1/5041_98423808305_40796308305_1960517_6704612_s.jpg", "source": "http://sphotos.ak.fbcdn.net/hphotos-ak-snc1/hs085.snc1/5041_98423808305_40796308305_1960517_6704612_n.jpg","link": "http://www.facebook.com/photo.php?pid=1960517&id=40796308305","comments": { "data": [ { "id": "98423808305_1152797", "from": { "name": "Caitlin Catherine Kennedy", "id": "1658825260" },"paging": { "next": "https://graph.facebook.com/98423808305/comments?limit=25&offset=25" } }}

HATEOAS

Architecture

Client

DomainData

Source

RESTWeb

Server DB

JavaScript calls REST API to get

Json array

What REST is not Silver bullet Not easy although simple Isn’t tied to the web Not perfect

– Client holds application state – Latency– Integrity

Summary REST is HTTP done right Architecture style Not so easy to get right Trend is towards APIs