Web REST APIs Design Principles
5 likes2,855 views
The document provides best practices for designing web APIs, including: - Taking an "outside-in" approach by focusing on the developer experience rather than internal systems. - Using plural nouns and concrete names for resources and avoiding verbs in base URLs. - Supporting pagination, search, and multiple response formats like JSON. - Implementing authentication, versioning, and error handling following common standards.
Web REST APIs Design Principles
- 1. Web API Design B Anjaneyulu Reddy
- 2. "pragmatic" REST "pragmatic" definition: Dealing with things sensibly and realistically in a way that is based on practical rather than theoretical considerations. "Outside-in" approach What are we trying to achieve with an API? The API's job is to make the developer as successful as possible. The orientation for APIs is to think about design choices from the application developer's point of view.
- 3. API ~ WiFi APIs should be like the wifi. Any device can connect to it and use all the functionalities. What is the design with optimal benefit for the app developer?
- 4. Nouns - good; verbs - bad Thumb rule: Keep simple things simple Simple and intuitive base URL Affordance is a design property that communicates how something should be used without requiring document. There should be only 2 base URLs per resource. Example: /dogs /dogs/1234
- 5. Nouns - good; verbs - bad Keep verbs out of base URLs This will lead to: ● Long list of URLs ● No consistent pattern Which will make it difficult for developers to learn and use.
- 6. Nouns - good; verbs - bad HTTP verbs for rescue
- 7. Plural & concrete nouns ● Use either plural or singular names but be consistent. Ex: Foursquare: /checkins GroupOn: /deals Zappos: /product ● Concrete names are better than abstract Ex: API that access content in various form - blogs, videos, news articles and so on. - Abstract names: /items or /assets - Concrete names: /blogs, /videos, /news Aim for concrete naming & number of resources between 12 and 24
- 8. Simplify associations Problem Resources always have association relationships to other resources. Ex: Get all the dogs who belong to owner 13. The relationships can be more complex which leads URLs with multi level depth. Ex: /resource/identifier/resource/identifier/resource In this case: /owner/13/dogs Solution: sweep complexity behind HTTP "?" Ex: /dogs?owner=13&color=red
- 9. Handling errors (1/5) ● Web API is a black box for developer ● error codes becomes a key tool to provide context and visibility to use APIs Best practices for designing error codes: ● Use HTTP status codes ● Make messages returned in the payload as verbose as possible
- 10. Handling errors (2/5) 1. Use HTTP status code ● Try and map the status codes to relevant standard- based codes ● The are around 70 HTTP status codes. Use only those which are very common
- 11. Handling errors (3/5) How many status codes should we use? The are only 3 real outcomes: ● Everything worked - success ● The application did something wrong - client error ● The API did something wrong - server error
- 12. Handling errors (4/5) Start using with few (say 3) codes and add as per the requirement. But should not be more than 8. Sample codes: ● 201 - Created ● 304 - Not Modified ● 404 - Not Found ● 403 - Forbidden ● 401 - Unauthorised It is important that the code that is returned is something that can be consumed and acted upon by the developer. Click here to get the complete list of HTTP error codes.
- 13. Handling errors (5/5) 2. Additional information in response message ● Use plain language to describe the error ● Link to more information page related to the error in the description is highly recommended
- 14. Versioning Never release an API without at version and make the version mandatory. Twilio: /2010-04-01/accounts Facebook: ?v=1.0 How to think about versioning? ● Specify the version with a 'v' prefix ● 'v' tag should have the highest scope: (ex: /v1/dogs) ● Avoid dot notation in versions (ex: v1, v2)
- 15. Pagination Support partial response by adding optional fields in a comma delimited list Linkedin: /people:(id,first-name,last-name,industry) Facebook: /joe.smith/friends?fields=id,name,picture Google: ?fields=title,media:group(media:thumbnail) Use limit and offset to make it easy for developers to paginate objects Facebook: offset 50 and limit 25 Linkedin: start 50 and count 25 Twitter: page 3 and rpp 25 (records per page)
- 16. Non resource responses Use verbs not nouns for all the APIs that do not return a resource. For example: Calculate Translate Convert /convert?from=EURO&to=USD&amount=100 Separate out a section of documentation for all the non resource returning requests.
- 17. Multiple formats Support more than one format for returning resources. Google data: ?alt=json FourSquare: /venue.json (recommended) Recommendations: ● Use JSON as default format ● Follow JavaScript conventions for naming attributes: ○ Use medial capitalisation (aka CamelCase) ○ Use uppercase or lowercase depending on the object.
- 18. Tips for search Global search /search?q=foo+bar (Google approach) Scoped search /owners/5283/dogs?q=foo+bar Note: Parameter 'q' indicates a search query.
- 19. Subdomain for APIs Consolidate all API requests in a single subdomain. api.facebook.com graph.facebook.com api.foursquare.com api.twitter.com stream.twitter.com search.twitter.com
- 20. Authentication Recommendation: Use the latest OAuth Facebook: OAuth 2.0 Twitter: OAuth 1.0a PayPal: Permission service API
- 21. API facade pattern (1/4) Credible, relevant and differentiated
- 22. API facade pattern (2/4) Three steps approach: ● Design the ideal API Design the URLs, request parameters and responses, payloads, headers, query parameters, and so on. The API design should be self consistent ● Implement the design with data stubs User temporary data without connecting to the internal system. ● Mediate (or) integrate between the facade and the systems One big problem -> 3 smaller problems
- 23. API facade pattern (3/4) Focus on app developer. API should be: ● Easy to use ● Self-consistent ● Intuitive
- 24. API facade pattern (4/4)
- 25. References ● Apigee design document: http://goo.gl/5uDdn ● Wikipedia ○ API: http://en.wikipedia.org/wiki/Api ○ HTTP Status codes: http://goo.gl/muq8s