usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)
-
Upload
javier-ramirez -
Category
Software
-
view
389 -
download
0
description
Transcript of usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)
![Page 1: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/1.jpg)
USABLE REST APIs
{ "_links":{ "author": {"href":"http://javier-ramirez.com"}, "work": {"href":"https://teowaki.com"}, "twitter": {"href":"https://twitter.com/supercoco9"}
} }
![Page 2: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/2.jpg)
Bedale, North of England
![Page 3: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/3.jpg)
a randompostbox in Bedale
![Page 4: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/4.jpg)
a usabilityproblem
![Page 5: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/5.jpg)
everybody agrees web usability is a good investment
![Page 6: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/6.jpg)
API usability? meh
http://docs.aws.amazon.com/AWSECommerceService/2011-08-01/DG/rest-signature.html
![Page 7: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/7.jpg)
![Page 8: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/8.jpg)
![Page 9: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/9.jpg)
![Page 10: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/10.jpg)
![Page 11: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/11.jpg)
![Page 12: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/12.jpg)
![Page 13: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/13.jpg)
Web usability is an approach to make web sites
easy to use for an end-user, without the requirement that any specialized training be
undertaken.
![Page 14: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/14.jpg)
LearnabilityEfficiencyMemorabilityErrorsSatisfaction
Usability 101, the 5 quality components by Jakob Nielsen
![Page 15: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/15.jpg)
![Page 16: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/16.jpg)
EFFECTIVE IMMEDIATELY!! NO MORE TYPEWRITERS ARE TO BE PURCHASED, LEASED, etc., etc. Apple is an innovative company. We must believe and lead in all areas. If word processing is so neat, then let's all use it!
Mike Scott, Apple President, 1980
![Page 17: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/17.jpg)
![Page 18: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/18.jpg)
Succeed consistently
Fail consistently
![Page 19: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/19.jpg)
twitter200 OK Success!304 Not Modified400 Bad Request401 Unauthorized403 Forbidden404 Not Found406 Not Acceptable420 Enhance Your Calm500 Internal Server Error502 Bad Gateway503 Service Unavailable
Useful Status429 Too many requests204 No Content
teowaki200 OK Success!201 Created202 Accepted301 Moved Permanently304 Not Modified401 Unauthorized403 Forbidden404 Not Found406 Not Acceptable422 Unprocessable Entity406 Not Acceptable500 Internal Server Error
![Page 20: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/20.jpg)
speed or at least asynchronous operations
![Page 21: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/21.jpg)
different users
different nerds needs
![Page 22: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/22.jpg)
netflix REST apiresource based
![Page 23: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/23.jpg)
netflix REST apiexperience based
http://www.slideshare.net/danieljacobson/api-revolutions-16755403
![Page 24: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/24.jpg)
all your format
are belong to us
*even native formats
![Page 25: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/25.jpg)
formats
![Page 26: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/26.jpg)
CORS: Cross origin resource sharing
![Page 27: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/27.jpg)
Don't expose your implementations details Resources are not models
![Page 28: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/28.jpg)
Easier to understand
Change the internals without breaking the contract
Resources based on business objects are more resistant to versioning
More opacity means more security
![Page 29: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/29.jpg)
REST
![Page 30: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/30.jpg)
REST Highlights you should know about but not necessarily implement
client-server,stateless,layered,cacheable Resources
Resource IdentifiersResource metadata
Uniform interfaceoperationsRepresentationsRepresentation metadata
HATEOAS (Hypermedia)Optionally: code on demand
![Page 31: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/31.jpg)
Hypermedia
Navigable APIs
![Page 32: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/32.jpg)
API pagination
![Page 33: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/33.jpg)
API links------Next steps
![Page 34: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/34.jpg)
Several resources in a single request
![Page 35: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/35.jpg)
Versioning without versions
![Page 36: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/36.jpg)
HAL:HypermediaApplicationLanguage
extra ball => http://stedolan.github.io/jq/
![Page 37: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/37.jpg)
empty new resources> curl “https://api.teowaki.com/teams/5677-dev”
![Page 38: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/38.jpg)
Partial Responses
teowaki's approach
api.teowaki.com/people/tw?api_quiet=true&api_links=false
Google's approach
www.googleapis.com/youtube/v3/videos?part=snippet&fields=items(id,snippet(title,position))
![Page 39: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/39.jpg)
Where to put your metadata In your HTTP Headers?
As request params and response fields?
Both?
Don't worry too much. Just choose one and stick to it
![Page 40: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/40.jpg)
![Page 41: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/41.jpg)
![Page 42: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/42.jpg)
Don't just implement. ThinkShould the API allow asynchronous creation, update and deletion? => return-async
Should it return the created/deleted/updated object or just a status code? =>return-representation
Should it ignore extra params transparently or should it warn you? => api_strict_mode
Should it allow for bulk updates/deletions on collections? => PATCH /user/links
Think of your own questions. There are not good or bad answers
![Page 43: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/43.jpg)
self-documentedAPI
![Page 44: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/44.jpg)
![Page 45: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/45.jpg)
don't let your APIbe the poobox whereyour userspost theirrequests
Moral of this talk
![Page 46: usable rest apis, by Javier Ramirez from teowaki (Apidays Mediterranea)](https://reader034.fdocuments.in/reader034/viewer/2022052618/554f49fbb4c905b9508b47dd/html5/thumbnails/46.jpg)
Find related links at
https://teowaki.com/teams/javier-community/link-categories/apis
Thanks!Gr ciesà
Javier Ramírez@supercoco9
rubyc kiev 14