Public API & Webhooks
Let external developers and integrations interact with your product programmatically via a documented REST API and outbound webhooks.
Options
API Type*
API Authentication*
Webhooks
Decision Points
Will external developers build integrations or products on top of your API?
If yes
Invest in REST + OAuth 2.0 + basic webhooks. Good DX (docs, SDKs) is as important as the API itself.
If no
API keys with REST is sufficient for internal automation and simple integrations.
Do your customers need real-time event delivery to their systems?
If yes
Add webhooks with retry logic and delivery guarantees. Basic webhooks break under load.
If no
Skip webhooks or use basic — most integrations can poll or tolerate eventual consistency.
REST, GraphQL, or gRPC?
If yes
Default to REST — universal, cacheable, documented with OpenAPI. Add GraphQL for complex mobile/dashboard clients; gRPC only for internal service-to-service.
If no
REST alone covers 90% of public APIs — resist polyglot until a specific consumer need forces it.
Public API or internal-only?
If yes
Public: invest in OpenAPI docs, SDKs, a status page, and versioning — public APIs are a contract you cannot break.
If no
Internal: skip the polish and iterate fast — breaking changes are cheap.
Versioning: URL, header, or date-based?
If yes
URL versioning (/v1/, /v2/) is simplest and most discoverable. Date-based (Stripe-style) is best for many small changes over time.
If no
Header versioning is cleaner in theory but breaks exploration with curl and docs — avoid.
Do you ship SDKs in multiple languages or only an OpenAPI spec?
If yes
Generate SDKs from OpenAPI (Speakeasy, Fern, Stainless) — maintaining hand-written SDKs in 5 languages is a full-time job.
If no
Publish a clean OpenAPI spec and let customers generate their own — minimum viable path.
Auth: API keys, OAuth 2, or mutual TLS?
If yes
API keys for server-to-server, OAuth 2 for user-delegated access, mTLS for high-security B2B integrations.
If no
Start with API keys; add OAuth only when third parties need to act on behalf of users.
Do you need scoped keys (read-only, per-resource)?
If yes
Model scopes as a bitmask or list on the key record — lets customers issue narrowly-scoped tokens for integrations.
If no
Single-scope keys (full account access) are simpler but raise blast radius on leaks.
Is API usage metered for billing?
If yes
Counter events per key in a metering store (Orb, Metronome) — never bill from analytics. Enforce at the gateway so usage-based limits apply before your app runs.
If no
Basic per-key request counters for rate limiting are enough.
Webhook callbacks or purely request/response?
If yes
Offer outbound webhooks — customers need push for anything they would otherwise have to poll. HMAC-sign payloads.
If no
Request/response is sufficient for synchronous integrations — offer polling endpoints for state.
Are bulk/batch endpoints required?
If yes
Ship a batch endpoint that accepts an array and returns per-item status — essential for import/export workflows.
If no
Per-item endpoints with good rate limits cover most cases.
Do you need async endpoints that return job IDs?
If yes
Return 202 Accepted with a job ID and a polling/webhook path — required for any operation > 30s (exports, imports, heavy queries).
If no
Synchronous responses are simpler — timeout budget capped at 30s.
Should responses support sparse fieldsets?
If yes
Add a `fields` query param (JSON:API style) or expose GraphQL — useful when payloads are large and mobile clients need only subsets.
If no
Return full resource representations — simpler and CDN-cacheable.
Pagination: cursor or offset?
If yes
Cursor-based (opaque token) — stable under inserts and scales to large result sets. Stripe-style.
If no
Offset pagination is fine only for small, stable datasets — breaks when items shift.
Will you expose a public playground (GraphiQL, Swagger UI)?
If yes
A hosted playground (Swagger UI, GraphiQL, or Scalar) dramatically improves DX for public APIs — host behind auth if the schema is sensitive.
If no
OpenAPI spec + curl examples in docs is enough for internal APIs.
Do partners need a sandbox environment?
If yes
Stand up a sandbox tenant with test data and test-mode API keys — required for any payments/banking integration and most enterprise deals.
If no
Production-only is fine for read-only or internal APIs.
Errors: RFC 7807 problem details or custom shape?
If yes
RFC 7807 (application/problem+json) is the standard — consistent across ecosystems and tool-friendly.
If no
A custom `{error: {code, message, details}}` shape is fine if you document it and keep it stable.
Rate limits: per key, per IP, or per endpoint?
If yes
Per-API-key as the primary axis, per-IP as anti-abuse, per-endpoint for expensive operations (AI, search). Return `X-RateLimit-*` headers.
If no
Per-key-only is enough for low-volume APIs — add IP limits at the edge (Cloudflare) later.
Tradeoffs
Powerful for clients but requires schema design discipline; N+1 queries are a common pitfall
Enables third-party integrations but requires an authorization server and token management
Event ordering, deduplication, and retry logic become your responsibility