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

Running a Public API Do's and Don'ts

Running a Public API Do's and Don'ts


Sibiu Web Meetup

October 18, 2019

More Decks by Sibiu Web Meetup

Other Decks in Programming


  1. Running a Public API Running a Public API Do's and

    Don'ts Do's and Don'ts Sibiu Web Meetup #7 - Oct 18, 2019 Jakob Cosoroabă
  2. Jakob Jakob Cosoroabă Cosoroabă Full Stack Developer Product Developer VP

    of "git blame" Tsar of "wait what?" the smarter platform for legal intelligence
  3. Sibiu Web Meetup #1 - Nov 23, 2018

  4. Consumer Consumer OH so Many Government APIs Producer Producer 1M/day

    request Legal Data
  5. What this talk is NOT about What this talk is

    NOT about SOAP vs REST vs GraphQL JSON vs XML vs GRPC JsonAPI vs WDSL
  6. The Basics The Basics

  7. What is a public API What is a public API

    used by 3rd parties public documentation
  8. Read-only APIs? Read-only APIs? J JA AMStack MStack


  10. Avoid NIHS Avoid NIHS Not Invented Here Syndrome Not Invented

    Here Syndrome use api gateways/proxy instead of coding yourself all the basic stuff
  11. - Pablo Ruiz Picasso Jakob NOW-

  12. Must Do Must Do

  13. design first design first

  14. free thinking free thinking API endpoints don't have to follow

    API endpoints don't have to follow internal structure internal structure
  15. Versioning Versioning /v1 x-api-version=2019-10-22

  16. Valid Documentation Valid Documentation

  17. Errors Errors

  18. Sane Formats Sane Formats (tweet since removed) (tweet since removed)

  19. Error 007 Error 007

  20. Use the Right Status Use the Right Status

  21. HTTP Response HTTP Response Headers Headers

  22. x-request-id x-request-id

  23. X-RateLimit-Remaining X-RateLimit-Remaining https://stackoverflow.com/questions/1602 2624/examples-of-http-api-rate-limiting- http-response-headers

  24. Retry-After Retry-After https://tools.ietf.org/html/rfc7231#section- 7.1.3

  25. x-credits-left x-credits-left

  26. Cteonnt-Length Cteonnt-Length https://twitframe.com/show? url=https://twitter.com/jcsrb/status/11593896 37066051585

  27. Don't Don't

  28. do not use a browser do not use a browser

    for testing too much for testing too much magic magic ♂ ♂ ♂ ♂ ♂ ♂ https://www.ietf.org/rfc/rfc3986.txt
  29. products/1 products/1 products/2 products/2 products/3 products/3

  30. POST /email/deliver POST /email/deliver

  31. Should Do Should Do

  32. Idempotence Idempotence

  33. Actor Tracking Actor Tracking

  34. Offer ASYNC Offer ASYNC

  35. Sandbox Sandbox

  36. Security Security

  37. CORS CORS Signed Webhooks Signed Webhooks Known Origin Known Origin

  38. Nice to have Nice to have

  39. Dashboard Dashboard Multi WebHook Multi WebHook Status Page Status Page


  41. Remove Fields Remove Fields

  42. DELETE with Params DELETE with Params


  44. Our API Business hours are from 9 - 12, Our

    API Business hours are from 9 - 12, 13-17 Monday to Friday except Public 13-17 Monday to Friday except Public holidays holidays
  45. Tools Tools

  46. API Testing API Testing curl insomnia postman API Proxy API

    Proxy Kong Tyk.io Express Gateway AWS/Azure Gateway
  47. API Definitions API Definitions RAML API Blueprint (apiary) OpenAPI Specification

    API Starter Kits API Starter Kits Node Laravel Rails https://github.com/feredean/node-api-starter https://github.com/joselfonseca/laravel-api https://guides.rubyonrails.org/api_app.html
  48. Thanks Thanks and don't build don't build