11 Tips for better APIs

Transcript

1. 11 Tips for better APIs @FanieReynders Team Lead – EOH Microsoft Services
2. “ ” An application programming interface a protocol intended to be used as an interface by software components to communicate with each other. - Wikipedia
3. API Design  Start from “outside-in”  “What are we trying to achieve?”  Developer as the user  Design communicates usage  Use best practice guidelines
4. “ ” Affordance is a design property that communicates how something should be used without requiring documentation. conflict between design affordance and documentation
5. Use nouns, not verbs  Keep things simple  Simple & intuitive base URLs  No verbs in base URLs  2 base URLs per resource  Collection - /cars  Single element - /cars/31
6. Use verbs for operations  POST, GET, PUT, DELETE  CRUD Resource POST GET PUT DELETE /cars Create a new car List cars Bulk update cars Delete all cars /cars/2615 Error Show car 2615 Update car 2615, if not exist, error Delete car 2615
7. Be consistent  Allows developers to predict  Avoid mixes of plural & singular  Concrete names are better than abstractions
8. Simplify associations  Limit routes to /resource/identifier/resource  Sweep complexity under the ‘?’ /cars/2615/drivers?from=jhb&since=2004 rather than /cars/2615/drivers/jhb/2004
9. Error handling  Standard HTTP codes – use them  Everything worked – success (200 OK)  The application did something wrong – client error (400 Bad Request)  The API did something wrong – server error (500 Internal Server Error)
10. Error handling  Include user-friendly messages  Link to more info 401 – Unauthorized { Message: “The API key provided is not valid”, ErrorId: 273343, MoreInfo: “http://dev.someapi.net/errors/273343 }
11. Versioning  Never release without  Must be highest scope  Use simple ordinal numbers  v1 not v1.2
12. Partial responses  Scoped response /cars?fields=id,name  Use limits & offsets with defaults  Provide meta-data  Support multiple formats  JSON (default)  XML  Atom
13. Non-resource responses  Use verbs, not nouns  Calculate  Convert  Project
14. What about Search?  Scoped search /cars/2231/drivers?q=Fanie  Global search /search?q=Fanie
15. Authentication  NEVER send passwords through the wire  Use SSL  OAuth
16. Consolidate  Cleaner & easier  Keep API separate from documentation  http://api.somesite.net  http://developers.somesite.net  Provide SDK
17. That’s all folks!