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
![Page 1: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/1.jpg)
Lecture L18REST API Design
![Page 2: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/2.jpg)
What is REST? An architectural style
– Representational State Transfer REST is defined in Roy Fielding’s
dissertation from 2000
![Page 3: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/3.jpg)
Adoption of REST
![Page 4: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/4.jpg)
Why REST Scalability Generality Independence Latency Security Encapsulation
![Page 5: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/5.jpg)
![Page 6: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/6.jpg)
HATEOASHypermediaAsTheEngineOfApplicationState
![Page 7: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/7.jpg)
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
![Page 8: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/8.jpg)
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
![Page 9: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/9.jpg)
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
![Page 10: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/10.jpg)
Better understanding Representational State Transfer
Client gets information about the data from the SERVER
CLIENT SERVER
RESOURCE DATASESSION DATA
URI REQUEST
RESOURCE
HYPERMEDIA Stateless
![Page 11: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/11.jpg)
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)
![Page 12: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/12.jpg)
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
![Page 13: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/13.jpg)
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”)
![Page 14: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/14.jpg)
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
![Page 15: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/15.jpg)
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
![Page 16: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/16.jpg)
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
![Page 17: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/17.jpg)
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
![Page 18: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/18.jpg)
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
![Page 19: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/19.jpg)
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
![Page 20: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/20.jpg)
Resources Nouns, not verbs
– Examples: Account, Group, Customer– Not behavior
Two types– Collection of resources– Instance of a resource
/applications/applications/7828
![Page 21: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/21.jpg)
REST Behavior GET to get resource POST to add resource PUT to update resource DELETE to delete resource HEAD to get header information
![Page 22: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/22.jpg)
Getting
Adding
Updating
GET someservice.com/api/customer/3829
POST someservice.com/api/customer/
REST examples
PUT someservice.com/api/customer/3829
![Page 23: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/23.jpg)
GET On the parent resource: collection
GET /users/789
200 OK{ “users”: { “username”: “olandri”, ... }}
![Page 24: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/24.jpg)
GET On the parent resource, give me a specific
instanceGET /users/789
200 OK{ { “username”: “olandri”, ... }}
![Page 25: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/25.jpg)
POST as Create On the parent resource
POST /users{ “username”: “olandri”, “firstname”: “Ólafur Andri”, “lastname”: “Ragnarsson”}
201 CreatedLocation: https://api.ruber.com/users/789
![Page 26: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/26.jpg)
POST as Update On the parent resource
– Allows partial updates, which is important for complex data type
POST /users/789{ “username”: “olandri”,}
200 OK
![Page 27: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/27.jpg)
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
![Page 28: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/28.jpg)
Versions Two ways
URLhttps://api.ruber.com/v1
Media-TypeApplication/json;application&v=1
![Page 29: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/29.jpg)
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
![Page 30: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/30.jpg)
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}
![Page 31: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/31.jpg)
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
![Page 32: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/32.jpg)
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
![Page 33: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/33.jpg)
Resource Oriented Designhttp://www.example.com/lms/students/123
{"ID" : 123,"name": "Name of Student","SSN" : 123456789,"DateOfBirth" : "2001-01-01"
}
![Page 34: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/34.jpg)
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"
}]
}
![Page 35: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/35.jpg)
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
![Page 36: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/36.jpg)
Architecture
Client
DomainData
Source
CMS
RESTWeb
Server DB
![Page 37: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/37.jpg)
JavaScript calls REST API to get
Json array
![Page 38: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/38.jpg)
What REST is not Silver bullet Not easy although simple Isn’t tied to the web Not perfect
– Client holds application state – Latency– Integrity
![Page 39: L18 REST API Design](https://reader031.vdocuments.us/reader031/viewer/2022013110/5479b3f3b4af9f46698b4784/html5/thumbnails/39.jpg)
Summary REST is HTTP done right Architecture style Not so easy to get right Trend is towards APIs