Design of Web APIs – Arnaud Lauret

Written by Arnaud Lauret. This book is for API designers, who involves in designing the API as well for those who develop APIs. It mostly talks about the best practices of designing APIs including best naming practices, documentation practices, security approaches. As I have already involved in few API developments already after reading this book I hope, I can write/develop even better APIs.

Here are the few points this books is covering.

• API should be designed in the consumers view
• Below questions should be answered before designing every end point
  1. Who are the users?
  2. What they need to do?
  3. How they will do?
  4. What are all the inputs? How the user will get the inputs?
  5. What are all the outputs? How the user will use the outputs?
• Avoid code influence, architecture influence & organization influences on API designs
• Implement caching if possible
• To document follow standard approaches like OpenAPI
• Do not use short names
• Do not make the input or output more than 20 fields and 3 levels
• If possible give aggregated results instead of expecting user to call the API again
• For names maintain the consistency not like createdDate, dateOpened etc.,
• For paths maintain the consistency not like /requests,/assets etc.,
• For response maintain same consistency in the structure. For list response if array of objects is replied then maintain that everywhere do not change to object of arrays.
• For actions maintain the consistency not like get, read
• In the response put most important on top and least on the bottom. Same goes for error response.
• Do not expose unnecessary data. If needed encrypt the data.
• To avoid URL logging switch to POST instead of GET if needed.
• Do not make breaking changes. Adding is better than removing and replacing input/output properties. Same goes for error response.
• Do versioning in case of changes.
• Follow either one of the six approaches.
  1. Domain
  2. Path
  3. Query
  4. Header
  5. Content Negotiation
  6. User configuration
• Design with extensibility, (i.e) instead of boolean it is better to have String as status. It can be easily extended. Same List of errors is better than few errors.
• Design in such a way to make less calls
• Provide all necessary info in single call. After transfer request give back the balance.
• Compress the data
• Make connection persistent.
• Make use of ETTag and Cache Control headers
• Make HEAD calls to avoid latency wherever possible
• Think and implement in the context of the business.
• Documentation is crucial.
• Make use of OpenAPI specification for documentation. So many tools are there to generate document from OpenAPI file.
• Guidelines and documentation is important for consistent API
• Make sure the guideline rules are followed and remove that rule.
• Review and rewrite.