Running a Public API
Do's and Don'ts
🦄 💩
Sibiu Web Meetup #7 - Oct 18, 2019
Jakob Cosoroabă
Jakob Cosoroabă
Full Stack Developer
Product Developer
VP of "git blame"
Tsar of "wait what?"
the smarter platform for legal intelligence
Sibiu Web Meetup #1 - Nov 23, 2018
Consumer
- OH
- so
- Many
- 💩
- Government
- APIs
Producer
- 1M/day request 📈
- Legal Data
What this talk is NOT about
- SOAP vs REST vs GraphQL
- JSON vs XML vs GRPC
- JsonAPI vs WDSL
The Basics 🥕
What is a public API
- used by 3rd parties
- public documentation
Read-only APIs?
JAMStack
HTTPS 🦄
Avoid NIHS
Not Invented Here Syndrome
use api gateways/proxy instead of coding yourself all the basic stuff
- Pablo Ruiz Picasso Jakob NOW-
Must Do 👩💻
design first
free thinking
API endpoints don't have to follow internal structure
Versioning
/v1
x-api-version=2019-10-22
Valid Documentation
Errors 💣
Sane Formats
(tweet since removed)
Error 007
Use the Right Status
HTTP Response Headers
x-request-id
X-RateLimit-Remaining
https://stackoverflow.com/questions/16022624/examples-of-http-api-rate-limiting-http-response-headers
Retry-After
https://tools.ietf.org/html/rfc7231#section-7.1.3
x-credits-left
Cteonnt-Length
Don't 💩
do not use a browser for testing too much magic
🧙♂️🧙♂️🧙♂️
products/1
products/2
products/3
POST /email/deliver
Should Do 🦄
Idempotence
Actor Tracking
Offer ASYNC
Sandbox
Security 🚨
CORS
Signed Webhooks
Known Origin
Nice to have 🎂
Dashboard
Multi WebHook
Status Page
NEVER
💩💩💩💩
💣
Remove Fields
💣
DELETE with Params
💣
PUNCHCARDS
💣
Our API Business hours are from 9 - 12, 13-17 Monday to Friday except Public holidays
Tools
API Testing
- curl
- insomnia
- postman
API Proxy
- Kong
- Tyk.io
- Express Gateway
- AWS/Azure Gateway
API Definitions
- RAML
- API Blueprint (apiary)
- OpenAPI Specification
API Starter Kits
Copy of Running a Public API Do's and Don'ts
By Peter-Jakob Cosoroabă
