API Architecture That Integrators Actually Enjoy
Bad APIs leak implementation details—database IDs in URLs, inconsistent error shapes, pagination that breaks at scale. Good APIs feel boring: predictable resources, stable versioning, and errors a developer can fix without opening a support ticket.
Resource Design and Versioning
Use nouns, not verbs: POST /v1/invoices not POST /createInvoice. Nest related resources: /v1/customers/{id}/subscriptions. Version in URL path (/v1) for public APIs—header versioning confuses SDK generators. Deprecate with Sunset headers and 6–12 month notice.
// Consistent error envelope
{
"error": {
"code": "invoice_not_found",
"message": "Invoice inv_9921 does not exist.",
"request_id": "req_7x8k2m"
}
}Pagination, Filtering, Sorting
Cursor pagination for lists that grow unbounded. Document max page sizes (100 is standard). Filtering via query params with allowlists—never pass raw SQL fragments from clients. Include Link headers or next_cursor in JSON for discoverability.
Operational Excellence
- OpenAPI 3.1 spec generated from code or maintained as source of truth
- Rate limits: 100 req/min default, higher tiers documented
- Idempotency-Key header on POST for payment and provisioning endpoints
- Webhook signatures (HMAC-SHA256) with retry documentation
One integration partner churned because our errors returned HTML 500 pages from nginx. JSON errors with request IDs cut their debugging time by half and renewed the contract.
SDK and Developer Experience
Publish official SDKs for your top two languages—PHP and JavaScript cover most integrators. Generate from OpenAPI with hand-polished ergonomics for auth and pagination helpers. Developers forgive missing endpoints before they forgive confusing auth dance.
Sandbox environments with fake data and webhook replay tools accelerate partner onboarding. Document rate limit headers: X-RateLimit-Remaining, Retry-After. Nothing frustrates integrators like silent 429s without guidance.
Version internal and external APIs separately. Your mobile team can move faster on /internal/v2 while partners stay stable on /v1 for 18 months. Communication beats surprise breaking changes every time.
Publish changelog RSS or webhook for API consumers when deprecating fields. Silent schema changes break mobile apps on old versions still in App Store long tail. Maintain N-2 mobile version compatibility policy documented publicly so partners plan upgrades.
Testing and Contract Verification
Consumer-driven contract tests catch breaking changes before partners do—Pact or schema diff in CI on OpenAPI changes. Maintain synthetic monitors hitting critical endpoints every five minutes from multiple regions; uptime SLAs in enterprise contracts depend on provable availability data.
Document error codes exhaustively—machine-readable code field plus human message. Partners automate retry logic around documented transient codes instead of opening tickets asking what 503 means today.
Publish HMAC request-signing examples for server-to-server integrations with timestamp nonce replay protection. Ship Postman collections generated from OpenAPI in CI—this cuts partner tickets asking for sample curls already documented but buried in outdated PDFs.
Documentation as Product
Treat developer docs like product UI: searchable, versioned, with copy-paste examples that work when pasted. Broken docs cost more support hours than missing features. Assign doc updates to the same PR as API changes—CI fails if OpenAPI diff has no corresponding markdown changelog entry in repos enforcing this policy successfully.
Run breaking-change detection in CI comparing OpenAPI specs between branches. Partners integrate slowly—six-month deprecation windows for field removals are standard in B2B contracts. Communicate sunsetting in changelog emails, not only documentation footnotes nobody reads until integration breaks during their busiest season.
Frequently Asked Questions
REST vs GraphQL for enterprise?
REST wins for public APIs and caching. GraphQL fits complex mobile clients with varied data needs—accept higher operational complexity.
Should we use gRPC internally?
Yes between microservices in same VPC. Expose REST or GraphQL at the edge for external consumers.
How do we handle breaking changes?
Additive changes only in minor versions. Breaking changes require new major version with parallel support period.