l18 rest api design
DESCRIPTION
Forritun veflausna, hvort sem er fyrir neytendur (B2C) eða fyrirtækni (B2B) eru í sívaxandi mæli að nota API til að bjóða upp á þjónustur. Þetta opnar örðum hugbúnaðarhúsum leið til að bjóða upp á lausnir sem nota viðkomandi APi. Sem dæmi má nefna að margir nota Google Maps API til að birta kort t.d. hvar eitthvað er. Notkun API er einnig architecture style og þar kemur REST inn. Með því að aðskila viðmót og backvinnslu með API má ná fram skörpum skilum þarna á milli. Í þessum fyrirlestri er REST skoða sem leið til að búa til lausnir.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
verb
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
CMS
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