Crafting WEB API Design that Developers Love. Deep dive

Roman Bugaev, Senior developer at Adform

About us -

• 400+ high performance servers

• High availability load balancing and failover

• 200 000 requests per second

• Peta Bytes of data on 50+ servers

• Up to 20 releases per day

• Integrations• Facebook, Google, Adobe• Large e-shops and CMS platform• TV ads recognition • Adform Marketplace

Why?

~70% API – REST

"there is no 'official' standard for RESTful web

Interviews

Pragmatic REST

• REST is an architectural style and not a strict standard, it allows for a lot of flexibly

• The primary design principle when crafting your API should be to maximize developer productivity and success.

• Pragmatic REST is a design problem

• Keep simple things simple

Keep base URL simple & intuitive

• Nouns are good; verbs are bad

• 2 base URLs per resource• /users /users/1234

• Keep verbs out of your base URLs

• Use HTTP verbs to operate on the collections and elements.

• POST create GET read PUT update DELETE delete

How to pick the nouns for URLs.

• Plural rather than singular nouns• Foursquare /checkins

• Dropbox /files

• Facebook /me/friends

• Concrete rather than abstract names

• /items vs. /blogs, /news

Simplify associations

• GET /folders/5678/files • Get all files belonging to a specific folder

• POST /folders/5678/files • Create new file for that folder

Sweep complexity behind the ‘?’

• Attributes GET /cars?color=red&state=new&location=minsk

• Paging GET /cars?limit=25&offset=50

• Global Search GET /search?q=lamb

• Scoped Search GET /owners/5678/cars?q=lamb

Handling errors

• Developers learn to write code through errors

• Developers depend on well-designed errors at the critical times

Handling errors - Facebook

HTTP Status Code 200

{error:

{message: “Malformed access token <token>”,type: “OAuthException”,code: “190”

}}

Handling errors - Twilio

HTTP Status Code: 401

{status: "401",message: "Authenticate",code: 20003,info: "http://www.twilio.com/docs/errors/20003"

}

A couple of best practices

• Use HTTP status codes• Make messages returned in the payload as verbose as

possible• Code• Developer message• User message• More Info

Start by using the following 3 codes: • 200 – OK (success)• 400 - Bad Request (client error)• 500 - Internal Server Error (server error)

I ❤BEST PRACTICES

Tips for versioning

• salesforce.com/services/data/v20.0/sobjects/Account

• Facebook ?v=1.0

• The version is mandatory.

• Accept header for entity versioning

• Specify the version with a 'v' prefix.

• Use a simple ordinal number.

• Create an alias for current version

Actions

• Use verbs not nouns:• /convert?from=EUR&to=CNY&amount=100

• Make it clear in your API documentation that these “non-resource” scenarios are different.

Probe Web Resources Efficiently with OPTIONS in REST

< HTTP/1.1 200 OK

< Allow: GET, HEAD, POST, OPTIONS, TRACE

< Content-Type: text/html; charset=UTF-8

< Date: Wed, 13 December 2013 10:24:43 GMT

< Content-Length: 0

Probe Web Resources Efficiently with HEAD in REST

< HTTP/1.1 200 OK

< Accept-Ranges: bytes

< Content-Type: text/html; charset=UTF-8

< Date: Wed, 08 May 2013 10:12:29 GMT

< ETag: "780602-4f6-4db31b2978ec0"

< Last-Modified: Thu, 25 Apr 2013 16:13:23 GMT

< Content-Length: 1270

Scale

• Think about scale sooner that later

• Rate limits

• Extra servers

• Partitioning

• Caching • Between application and database

• In the application itself

• Using an API proxy

• CDN for large static content

Supporting multiple formats

• To get the JSON format from a collection or specific element: • dogs.json• /dogs/1234.json

Accept header for entity versioning also applicable

Default format: JSON

Follow JavaScript conventions

Chatty APIs

Imagine how developers will use your API• You can design a RESTful API and still mitigate the

chattiness.

Be complete and RESTful and provide shortcuts

Take advantage of the partial response syntax

• /owners/5678?fields=name, dogs.name

Some useful tools

Apiary.io

Apigee

Runscope, hurl.it, apichangelog

Mashape

Security

• Use something established

• API keys for non-sensitive data only

• Username/password auth for site based APIs

• OAuth for server-to-server APIs

• SSL for EVERYTHING sensitive

OAuth

1. An OAuth token gives one app access to one API on behalf of one user.

2. App developers do not want responsibility of holding a user’s secret information (password).

3. there are three entities (legs) – user/server/client

Why is OAuth important?

• What if client is hacked and someone steals all the passwords?• OAuth allows the API provider to revoke tokens for an

individual user and for an entire app

• On the other hand, if user decides to change his password, the token will be the same.

• Developers can use an OAuth library in their language

Types of OAuth 2.0

• BEARER TOKEN • SSL and big numbers

• MAC TOKEN • Uses signature instead of SSL

• SAML• if you and your potential API developers don’t

understand SAML or know what it is, that’s a signal to stay away

Thank you! Questions?

rbugaev@gmail.com

bugaev_roman

http://twitter.com/rbugaev

http://facebook.com/rbugaev