Upload
javier-ramirez
View
3.194
Download
0
Tags:
Embed Size (px)
DESCRIPTION
With the adoption of REST, the proliferation of smartphones and tablets, and the second coming of JavaScript, exposing our applications as a service is now more important than ever. Lots of libraries and frameworks make really easy to create a (kinda) RESTful API but, in many occassions, these APIs are designed without really thinking on the developers that will have to use them. I want to talk about some of the points that can help making your API more developer-friendly. Some of the areas I’ll cover will be discoverability, authentication, headers, formats, parameters, documentation and tools.
Citation preview
USABLE REST APIs{ "_links":{ "author": {"href":"http://javier-ramirez.com"}, "work": {"href":"https://teowaki.com"}, "twitter": {"href":"https://twitter.com/supercoco9"}
} }
Bedale, North of England
a randompostbox in Bedale
a usabilityproblem
everybody agrees web usability is a good investment
API usability? meh
http://docs.aws.amazon.com/AWSECommerceService/2011-08-01/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
Succeed consistently
Fail consistently
huddle200 OK 201 Created202 Accepted400 Bad Request401 Unauthorized403 Forbidden404 Not Found410 Gone
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 Created304 Not Modified401 Unauthorized403 Forbidden404 Not Found422 Unprocessable Entity406 Not Acceptable500 Internal Server Error
speed or at least asynchronous operations
different users
different nerds needs
netflix REST apiresource based
netflix REST apiexperience based
http://www.slideshare.net/danieljacobson/api-revolutions-16755403
all your format
are belong to us
*even native formats
formats
CORS: Cross origin resource sharing
Don't expose your implementations details Resources are not models
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
REST
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
Hypermedia
Navigable APIs
API pagination
API links------Next steps
Several resources in a single request
Versioning without versions
HAL:HypermediaApplicationLanguage
extra ball => http://stedolan.github.io/jq/
empty new resources> curl “https://api.teowaki.com/teams/5677-dev”
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))
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
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
don't let your APIbe the poobox whereyour userspost theirrequests
Moral of this talk
Shameless self promotion If you enjoyed this presentation, please thank me by
registering on https://teowaki.com
It's a site for developers, you can hang around for free, and I think it's quite cool (but a bit buggy since we've just launched)
<3 <3 <3Javier Ramírez
@supercoco9