APIs: The good, the bad, the ugly
6 likes8,017 views
The document discusses the strengths and weaknesses of API documentation, highlighting good aspects like interactivity and consistency, while noting problems such as outdated information and inconsistencies in data formats. It also addresses authentication and error handling, emphasizing the importance of user-friendly error messages and stable methods for managing permissions. Lastly, it provides resources for further exploration of documentation standards and versioning.
APIs: The good, the bad, the ugly
- 1. APIs: The good, the bad, the ugly @MicheleTitolo
- 6. The Good
- 7. It exists
- 9. I/O Docs
- 10. The Bad
- 12. The Ugly
- 13. Documentation?
- 15. URLs
- 16. The Good
- 17. Consistency
- 19. The Bad
- 20. Inconsistency
- 21. /users/22445 /reviews/3156 /times/127 Not review or time id’s
- 22. The Ugly
- 23. “Send GET to /remove to delete”
- 25. Payloads
- 26. The Good
- 28. You have all the data you need
- 29. The Bad
- 30. Endpoint “id” field /products id /products/:id productID /cart product_id
- 31. Yes, this actually happened
- 32. Change
- 33. We expect certain things
- 34. ...like image urls having http://
- 35. ...like dates sent in the same format
- 36. We expect certain things to not change
- 37. The Ugly
- 41. Unstable
- 43. Authentication
- 44. The Good
- 45. HTTP Basc Auth over SSL
- 46. ...when SSL is secure
- 47. OAuth
- 48. The Bad
- 49. OAuth
- 51. The Ugly
- 54. Authorization
- 55. The Good
- 57. The Bad
- 58. A single API key
- 59. The Ugly
- 60. Authorization?
- 61. goto fail;
- 64. Errors
- 65. The Good
- 66. Error codes
- 67. Error message in response
- 69. The Bad
- 70. “There was an error”
- 72. The Ugly
- 76. Caching
- 77. The Good
- 78. Using one of the standards
- 79. Cache-Control
- 81. etags
- 82. The Bad
- 84. The Ugly
- 85. Caching
- 88. In Summary
- 89. Consistency
- 90. Conventions
- 91. Simple
- 93. • JSONSchema, RAML, API Blueprint, • HTTP 1.1 Spec: http://www.w3.org/Protocols/rfc2616/ rfc2616.html • Charles, Postman • http://runscope.com, also http://newrelic.com for backend analytics • Versioning: http://apiux.com/2013/05/14/api- versioning/ Q&A Resources