The API Spec
Even MORE lessons learned.
Where we left off...
- MicroServices as the Architecture
- Granularity, Scalability, Stability
- Services should be externalizable
References
-
Steve Yegge: Amazon vs Google - Platforms
-
Heroku API Design Guide
-
The RESTed NARWHL
Let's communicate...
HTTP
- Well-known concepts
- Extremely well supported
- Least Common Denominator
REST
- Stateless req / res pattern
- Endpoint = path, method
- Request = path, method, headers, body
- Response = statusCode, headers, body
More Specifically
- Paths are nouns, represent resources
- Methods are verbs, represent actions
- Status codes, headers have meaning
More MORE Specifically
- I DONT KNOW STOP PRESSURING ME
THE API SPEC!
Secured!
- Always HTTPS
- Ship self-signed certs
- Allow customers to provide
Style guide
- All endpoints support JSON
- CamelCase
- Use GUIDS for IDs
- Dates: ISO-8601
- createdOn, modifiedOn, createdBy, updatedBy
- Return full, unwrapped representations
- No custom HTTP verbs
- Custom actions always live under /actions
Headers
- Authentication is required
- Accepts for versioning. Default to v1.
- Respect Content-Type. Default to JSON.
- E-Tag for caching.
- Request-Id
- Request-Origin-Date
Protect Yourself
- Input validation with useful feedback
- Rate Limiting
- Drop stale requests
Self-Documenting
- OPTIONS requests on each endpoint
- Protos for input / output
- List supported methods & child routes
Errors!!!
The Well-Behaved Error
- All Services return exactly one error format
- statusCode
- name
- message
- messageCode
- source
- details
- upstreamError
- Can strip technical details based on client ID
ZeroMQ
- Dealer - Router pattern
- Request / Response parts as frames
- Separate routing logic from transport
I swear it's real! (Again)
This is a lot of work...
For Engineering
- "The Public" vs "The Other Team"
- Everything is an integration
- Time reading & using vs writing
For the Business
- Use your dev resources better
- You can expose your APIs. So DO!
- Interface possibilities