writing usable rest apis. javier ramirez

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