API Best Practices
- 1. API Best Practices @urilavi http://bit.ly/scisr
- 2. Public API/ Web API HTTP / HTTPS XML/JSON
- 3. Rule #0 http://www.flickr.com/photos/holeymoon/2131118247/
- 4. Rule #1 - Funnel Try Build Adopt
- 5. Simplicity? TDD public API At least 3 clients Different languages http://www.flickr.com/photos/giosp/3933753363/
- 6. Cross Cutting Concerns Authentication/Authorization Versioning Sync/Async Re-entrance Pagination Caching Throttling
- 7. RESTfulness * Use plural names (reads better with GET) * Avoid methods (it isn’t traversal and grows fast) Nouns (Method-less) 2 base URLS per resource /events /events/10
- 8. RESTfulness HTTP Verbs on collections/elements Create POST /events Fetch GET /events/12345 Update PUT /events/12345
- 9. Method-based * Use verbs * Make the documentation clear that these are “non resource” operations Convert Translate
- 10. Rule #2 - Relationships
- 11. Rule #2 - Relationships Keep it simple - 3 levels
- 12. Rule #2 - Relationships Keep it simple - 3 levels GET /lecturers/events/10
- 13. Rule #3 - Complexity? http://www.flickr.com/photos/takomabibelot/4373062612/
- 14. Rule #4 - Versioning * Maintain at least one version back GET api/v1/events/10
- 15. Rule #4 - Versioning * Maintain at least one version back GET api/v1/events/10
- 16. Rule #5 - Errors HTTP status codes {200, 400, 500} Verbose messages link to documentation
- 17. Rule #6 - Sync / Async Result available - sync Result available in x time - async PicScout’s API
- 18. Rule #7- Re-entrance http://www.flickr.com/photos/leovan/2152274834/ POST /funds/accounts/1000/ {‘value’: 100, ‘token’: ‘xbds213’}
- 19. Rule #8 - Formatting JaaD = JSON as a Default
- 20. Rule #9 - Automation? http://www.flickr.com/photos/r80o/39304743/ APIs are for humans