Roman Bugaev gives best practices for designing RESTful web APIs that developers love. He recommends keeping URLs simple with nouns rather than verbs, using HTTP verbs to operate on resources, and placing complex parameters after a question mark. For errors, use HTTP status codes and provide verbose payloads with code, message, and more info. Consider versioning, rate limiting, and supporting multiple formats like JSON.

1. Crafting WEB API Design that
Developers Love. Deep dive
Roman Bugaev, Senior developer at Adform

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. Why?
~70% API – REST
"there is no 'official' standard for RESTful web
Interviews

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. 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. 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. 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. 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. Handling errors
• Developers learn to write code through errors
• Developers depend on well-designed errors at the
critical times

10. Handling errors - Facebook
HTTP Status Code 200
{
error:
{
message: “Malformed access token <token>”,
type: “OAuthException”,
code: “190”
}
}

11. Handling errors - Twilio
HTTP Status Code: 401
{
status: "401",
message: "Authenticate",
code: 20003,
info: "http://www.twilio.com/docs/errors/20003"
}

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. 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. 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. 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. 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. 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. 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. 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. Some useful tools

21. Apiary.io

22. Apigee

23. Runscope, hurl.it, apichangelog

24. Mashape

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. 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. 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. 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. Thank you! Questions?
rbugaev@gmail.com
bugaev_roman
http://twitter.com/rbugaev
http://facebook.com/rbugaev