Lessons in Building APIs from From @ImgurAPI and Beyond 

Jasdev Singh @jasdev 4 Former iOS and API Engineer at Imgur 4 Organizer of Hack.UVA 4 Currently attending Recurse Center 

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 ! 

Topics 4 API Planning 4 Versioning 4 Routes 4 Documentation 4 Testing 4 Favorite Tools, Safeguards 4 API Support 

API Planning 

No content

Greenfield Project? Use a statically-typed language. Go, Scala, Swiftsoon 

"The best API designers are also API consumers." 

Versioning 

URL Versioning? Header Versioning? 

No content

Defining Your Routes 4 Resources (nouns) 4 Mapped onto the URL 4 Actions (verbs) 4 Reflected via HTTP methods: GET, POST, PUT, DELETE, etc. 

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 

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). 

Documentation "Documentation is the UX of your API." 

API Blueprint 4 Pure Markdown 4 Great tooling (including documentation generators) 4 Human readable, machine parsable 4 Example 

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." 

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. 

Favorite API Tools 4 Paw (OS X only) 4 Postman Safeguards 4 Rate-limiting by client and IP 4 HTTP 426 support (internal use) 

API Support 

4 Google Group 4 Stack Overflow tags 4 If a question comes up constantly, update the docs. 

Other Approaches 

4 HATEOAS 4 GraphQL 

Links 4 Twitter's Pagination Setup 4 Stripe's API Versioning 4 Building Stripe's API 

Questions? Comments? Thanks for listening and inviting me to speak! Slides and notes will be available at https://github.com/ jasdev/talks