Lessons in Building APIs

API lunch chat given at Goldman Sach's!

Transcript

1. Lessons in Building APIs from From @ImgurAPI and Beyond
2. Jasdev Singh @jasdev 4 Former iOS and API Engineer at Imgur 4 Organizer of Hack.UVA 4 Currently attending Recurse Center
3. Disclaimer: I don't know everything there is about APIs. However, I learned a lot during my time and Imgur and beyond. I hope you find something from this talk applicable !
4. Topics 4 API Planning 4 Versioning 4 Routes 4 Documentation 4 Testing 4 Favorite Tools, Safeguards 4 API Support
5. API Planning
7. Greenfield Project? Use a statically-typed language. Go, Scala, Swiftsoon
8. "The best API designers are also API consumers."
9. Versioning
10. URL Versioning? Header Versioning?
12. Defining Your Routes 4 Resources (nouns) 4 Mapped onto the URL 4 Actions (verbs) 4 Reflected via HTTP methods: GET, POST, PUT, DELETE, etc.
13. Example 4 GET /products - Lists all products 4 GET /products/8 - Retrieves a specific product 4 POST /products - Creates a new product 4 PUT /products/8 - Update specific product 4 DELETE /products/8 - Delete a specific product
14. Parameters 4 Avoid sticking parameters in routes. Defer to query parameters or form data. 4 e.g. GET /products/search?q=:query instead of GET / products/search/:query 4 Other examples include pagination, like page and per_page. Important to return pagination information in the response (links to the next, previous, first, and last pages of a given collection).
15. Documentation "Documentation is the UX of your API."
16. API Blueprint 4 Pure Markdown 4 Great tooling (including documentation generators) 4 Human readable, machine parsable 4 Example
17. Testing Your Documentation with DREDD "Dredd is a language agnostic command-line tool for validating API documentation written in API Blueprint format against its backend implementation."
18. Additional Tips 4 Each example is worth a page of documentation. Users should be able to quickly copy sample cURL requests and hit the ground running. 4 If the user is logged in and has a client registered, make all examples use their API key.
19. Favorite API Tools 4 Paw (OS X only) 4 Postman Safeguards 4 Rate-limiting by client and IP 4 HTTP 426 support (internal use)
20. API Support
21. 4 Google Group 4 Stack Overflow tags 4 If a question comes up constantly, update the docs.
22. Other Approaches
23. 4 HATEOAS 4 GraphQL
24. Links 4 Twitter's Pagination Setup 4 Stripe's API Versioning 4 Building Stripe's API
25. Questions? Comments? Thanks for listening and inviting me to speak! Slides and notes will be available at https://github.com/ jasdev/talks