Создание API, которое полюбят разработчики. Глубокое погружение
0 likes4,620 views
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.
More Related Content
What's hot (20)
Similar to Создание API, которое полюбят разработчики. Глубокое погружение (20)
More from SQALab (20)
Recently uploaded (20)
Создание API, которое полюбят разработчики. Глубокое погружение
- 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
”, 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
- 21. Apiary.io
- 22. Apigee
- 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