building usable rest apis. by javier ramirez, teowaki. fowa london
TRANSCRIPT
USABLE REST APIs
{ "_links":{ "author": {"href":"http://javier-ramirez.com"}, "work": {"href":"https://teowaki.com"}, "twitter": {"href":"https://twitter.com/supercoco9"}
} }
Bedale, North Yorkshire
a randompostbox in Bedale
a usabilityproblem
everybody agrees web usability is a good investment
API usability? meh
http://docs.aws.amazon.com/AWSECommerceService/latest/DG/rest-signature.html
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.
LearnabilityEfficiencyMemorabilityErrorsSatisfaction
Usability 101, the 5 quality components by Jakob Nielsen
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
don't be too smart
follow best practices
Succeed consistently
Fail consistently
twitter200 OK Success!304 Not Modified400 Bad Request401 Unauthorized403 Forbidden404 Not Found406 Not Acceptable410 Gone420 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
speed or at least asynchronous operations
different users
different nerds needs
Javi, you are not an example
of anything
formats
CORS: Cross origin resource sharing
Where to put your metadata In your HTTP Headers?
As request params and response fields?
Maybe Both? It usually pays not to be too strict and just make your users' lives easier
Same content?
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))
netflix REST apiresource based
netflix REST apiexperience based
http://www.slideshare.net/danieljacobson/api-revolutions-16755403
Don't expose your implementations details Resources are not database tables
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
I shouldn't be ableto guess your programming languageby looking at your API
Hypermedia
Navigable APIs
API pagination
HAL:HypermediaApplicationLanguage
JSON-API
API links------Next steps
Several resources in a single request
Versioning without versions
empty new resources> curl “https://api.teowaki.com/teams/5677-dev”
URI templates
http://example.com/~{username}/ http://example.com/dictionary/{term:1}/{term} http://example.com/search{?q,lang}
self-documentedAPI
Swagger
Swagger
RAML
RAML
Don't just implement.
Think
Should my API allow asynchronous creation,
update, and deletion?
Should it return the contents of a newly created
or updated resource or just the id?
What about deleted resources?
Should my API ignore unrecognised parameters
silently, even when it is gettinga valid request, or should it
return an error?
Should it allow bulk operations?
PATCH /users/541,1001,3005
Does my API need a real-time or push mechanism
for updates?
Do I need to set usage quotas?
There are not good or bad answers. Each API has different needs.
The only wrong answer is copying and pasting fromyour last project and pretend the work is done.
LearnabilityEfficiencyMemorabilityErrorsSatisfaction
Remember:
don't let your APIbe the poobox whereyour userspost theirrequests
Moral of this talk
Find related links at
https://teowaki.com/teams/javier-community/link-categories/apis
Thanks!
Javier Ramírez@supercoco9