Создание API, которое полюбят разработчики. Глубокое погружение
Post on 15-Jan-2015
3999 Views
Preview:
DESCRIPTION
Transcript
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
top related