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
• P...
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 d...
Keep base URL simple & intuitive
• Nouns are good; verbs are bad
• 2 base URLs per resource
• /users
/users/1234

• Keep v...
How to pick the nouns for URLs.
• Plural rather than singular nouns
• Foursquare
• Dropbox
• Facebook

/checkins
/files
/m...
Simplify associations
• GET /folders/5678/files
• Get all files belonging to a specific folder

• POST /folders/5678/files...
Sweep complexity behind the ‘?’
• Attributes GET
/cars?color=red&state=new&location=minsk
• Paging GET /cars?limit=25&offs...
Handling errors
• Developers learn to write code through errors
• Developers depend on well-designed errors at the
critica...
Handling errors - Facebook
HTTP Status Code 200
{
error:
{
message: “Malformed access token <token>”,
type: “OAuthExceptio...
Handling errors - Twilio
HTTP Status Code: 401
{
status: "401",
message: "Authenticate",
code: 20003,
info: "http://www.tw...
A couple of best practices
• Use HTTP status codes
• Make messages returned in the payload as verbose as
possible
•
•
•
•
...
Tips for versioning
• salesforce.com
/services/data/v20.0/sobjects/Account
• Facebook ?v=1.0

• The version is mandatory.
...
Actions
• Use verbs not nouns:
• /convert?from=EUR&to=CNY&amount=100

• Make it clear in your API documentation that these...
Probe Web Resources Efficiently
with OPTIONS in REST
< HTTP/1.1 200 OK
< Allow: GET, HEAD, POST, OPTIONS, TRACE
< Content-...
Probe Web Resources Efficiently
with HEAD in REST
< HTTP/1.1 200 OK
< Accept-Ranges: bytes
< Content-Type: text/html; char...
Scale
• Think about scale sooner that later
• Rate limits
• Extra servers
• Partitioning
• Caching
•
•
•
•

Between applic...
Supporting multiple formats
• To get the JSON format from a collection or specific
element:
• dogs.json
• /dogs/1234.json
...
Chatty APIs
Imagine how developers will use your API
• You can design a RESTful API and still mitigate the
chattiness.
Be ...
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
1. An OAuth token gives one app access to one API
on behalf of one user.
2. App developers do not want responsibilit...
Why is OAuth important?
• What if client is hacked and someone steals all the
passwords?
• OAuth allows the API provider t...
Types of OAuth 2.0
• BEARER TOKEN
• SSL and big numbers

• MAC TOKEN
• Uses signature instead of SSL

• SAML
• if you and ...
Thank you! Questions?

rbugaev@gmail.com
bugaev_roman
http://twitter.com/rbugaev
http://facebook.com/rbugaev
Upcoming SlideShare
Loading in …5
×

Создание API, которое полюбят разработчики. Глубокое погружение

4,402 views

Published on

Доклад Романа Бугаева на конференции Application Developer Days-4. г.Минск 13 декабря 2013

Published in: Education, Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
4,402
On SlideShare
0
From Embeds
0
Number of Embeds
3,658
Actions
Shares
0
Downloads
12
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Создание API, которое полюбят разработчики. Глубокое погружение

  1. 1. Crafting WEB API Design that Developers Love. Deep dive Roman Bugaev, Senior developer at Adform
  2. 2. 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
  3. 3. Why? ~70% API – REST "there is no 'official' standard for RESTful web Interviews
  4. 4. 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
  5. 5. 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
  6. 6. How to pick the nouns for URLs. • Plural rather than singular nouns • Foursquare • Dropbox • Facebook /checkins /files /me/friends • Concrete rather than abstract names • /items vs. /blogs, /news
  7. 7. Simplify associations • GET /folders/5678/files • Get all files belonging to a specific folder • POST /folders/5678/files • Create new file for that folder
  8. 8. 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
  9. 9. Handling errors • Developers learn to write code through errors • Developers depend on well-designed errors at the critical times
  10. 10. Handling errors - Facebook HTTP Status Code 200 { error: { message: “Malformed access token <token>”, type: “OAuthException”, code: “190” } }
  11. 11. Handling errors - Twilio HTTP Status Code: 401 { status: "401", message: "Authenticate", code: 20003, info: "http://www.twilio.com/docs/errors/20003" }
  12. 12. 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 I ❤ BEST PRACTICES Start by using the following 3 codes: • 200 – OK (success) • 400 - Bad Request (client error) • 500 - Internal Server Error (server error)
  13. 13. 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
  14. 14. 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.
  15. 15. 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
  16. 16. 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
  17. 17. 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
  18. 18. 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
  19. 19. 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
  20. 20. Some useful tools
  21. 21. Apiary.io
  22. 22. Apigee
  23. 23. Runscope, hurl.it, apichangelog
  24. 24. Mashape
  25. 25. 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
  26. 26. 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
  27. 27. 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
  28. 28. 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
  29. 29. Thank you! Questions? rbugaev@gmail.com bugaev_roman http://twitter.com/rbugaev http://facebook.com/rbugaev

×