Why it matters
A product API turns the actions customers can take in your UI into a dependable integration surface. A machine-readable contract makes those actions discoverable to developers, generated clients, CLIs, and AI tools. The contract is a map of what the product can do; it does not replace authorization or good workflow design.
REST with OpenAPI and GraphQL with a documented schema are both workable choices. What matters is that meaningful customer operations have stable names, typed inputs and outputs, clear errors, and a versioning story. Keep the contract aligned with the behavior people actually see in the product.
Decisions to make
- Choose REST, GraphQL, or a deliberate mix based on customer workflows and the way clients will use them.
- Decide which customer-visible actions and data must have programmatic parity with the UI.
- Define resource identity, tenant scope, pagination, filtering, and asynchronous job behavior.
- Describe request, response, and error shapes, including examples and the meaning of each field.
- Choose user-delegated authorization, scoped API keys, or both for different clients.
- Set compatibility, deprecation, and change-review rules for the published contract.
Build checklist
- Publish the OpenAPI document or GraphQL schema alongside task-oriented API documentation.
- Give each operation a stable name, useful description, typed inputs, and a predictable result.
- Enforce the same tenant and permission checks used by the product UI on every request.
- Add pagination, idempotency, and asynchronous status where customer workflows need them.
- Test examples and generated clients against a running API so the contract cannot silently drift.
- Track UI workflows without an API path and either close the gap or explain the intentional exception.
Common mistakes
- Publishing a schema that documents endpoints but omits the customer tasks people need to finish.
- Treating a typed request as proof that its caller is authorized for the selected tenant.
- Changing fields or errors without a compatibility plan for existing integrations.
Tools & references
3 starting points to compare or study. Check fit, maintenance, terms and current capabilities before choosing one.
