Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Lessons in Building APIs

Lessons in Building APIs

API lunch chat given at Goldman Sach's!

Jasdev Singh

October 09, 2015

Transcript

25 slides
  1. Jasdev Singh @jasdev 4 Former iOS and API Engineer at

    Imgur 4 Organizer of Hack.UVA 4 Currently attending Recurse Center
  2. 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 !
  3. Topics 4 API Planning 4 Versioning 4 Routes 4 Documentation

    4 Testing 4 Favorite Tools, Safeguards 4 API Support
  4. Defining Your Routes 4 Resources (nouns) 4 Mapped onto the

    URL 4 Actions (verbs) 4 Reflected via HTTP methods: GET, POST, PUT, DELETE, etc.
  5. 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
  6. 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).
  7. API Blueprint 4 Pure Markdown 4 Great tooling (including documentation

    generators) 4 Human readable, machine parsable 4 Example
  8. 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."
  9. 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.
  10. Favorite API Tools 4 Paw (OS X only) 4 Postman

    Safeguards 4 Rate-limiting by client and IP 4 HTTP 426 support (internal use)
  11. 4 Google Group 4 Stack Overflow tags 4 If a

    question comes up constantly, update the docs.
  12. Questions? Comments? Thanks for listening and inviting me to speak!

    Slides and notes will be available at https://github.com/ jasdev/talks

More Decks by Jasdev Singh

Other Decks in Technology