Crafting WEB API Design that Developers Love. Deep dive Roman Bugaev, Senior developer at Adform
Jan 15, 2015
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?
bugaev_roman
http://twitter.com/rbugaev
http://facebook.com/rbugaev