Letting others build on you.
WHAT IT PROVIDES
Customers automating their own work Partners building on your product A route to integrations you did not build
WHAT IT COSTS
A contract you cannot break Documentation Support Security surface
WHY THE CONTRACT MATTERS MOST
Once published, changing it breaks other people's systems.
WHAT TO DESIGN CAREFULLY BEFORE PUBLISHING
Resource naming Authentication Pagination Error format Versioning
WHAT VERSIONING PROVIDES
The ability to change without breaking existing users.
WHAT TO TREAT AS BREAKING
Removing a field Changing a type or meaning Adding a required parameter Changing error behaviour
WHAT IS SAFE
Adding optional fields and new endpoints.
WHAT AUTHENTICATION TO USE
Tokens, scoped to permissions, revocable.
WHAT TO NEVER USE
The customer's password.
WHAT RATE LIMITING PROVIDES
Protection from one consumer degrading the service.
WHAT TO RETURN
Clear limits, and how long until reset.
WHAT DOCUMENTATION MUST INCLUDE
Every endpoint Authentication Examples that work Error meanings
WHAT TO PROVIDE
A way to test without affecting real data.
