TL;DR
- Internal API first: build for your own frontend; public-API later
- REST + JSON default; GraphQL only if you have multiple clients with very different needs
- Webhook FIRST, polling SECOND: most SaaS underbuilds webhooks
- Rate limit + auth from day 1: cheap to add early, expensive to retrofit
The 4-stage API maturity ladder
Stage 1: Internal API for your frontend (always)
Frontend calls backend. JSON over HTTPS. Auth via session cookie or JWT. No public docs. This IS your API at MVP stage.
Stage 2: Webhook OUT to customers (week 4 of operations)
When something happens in your system (order placed, user signed up, payment received), POST to customer-defined URL. Add this BEFORE any pull-API. Customers want push, not poll.
Stage 3: Read API (when 5+ customers ask)
Public REST endpoints to GET data. Token auth. Per-customer rate limit. Versioning (v1/) baked in. Documented (Swagger / Stoplight / Mintlify).
Stage 4: Write API (when integrations are critical)
POST/PATCH/DELETE for customers to write to your system. This is the riskiest — every write needs validation, idempotency, atomicity. Most SaaS shouldn't expose this until Series A scale.
REST vs GraphQL in 2026
REST default for India SaaS:
- All Indian dev teams know REST
- Easier to debug, log, cache, secure
- Tooling (Postman, OpenAPI) is universal
GraphQL only if:
- You have web + mobile + 3rd-party clients with different needs
- Frontend team values flexibility over caching
- You can absorb the extra ops complexity
Auth + rate limiting
| Layer | Why |
|---|---|
| API key per customer (long-lived) | Server-to-server integrations |
| OAuth 2.0 (short-lived tokens + refresh) | 3rd-party app integrations |
| Per-key rate limit (e.g. 1000/hr default) | Prevent abuse + protect infra |
| Per-endpoint rate limit (heavy ones lower) | Protect expensive operations |
| Per-IP rate limit (additional layer) | Block bot traffic |
Webhooks done right
- Always POST JSON, never GET
- Sign every request with HMAC; let customer verify
- Retry with exponential backoff: 1m, 5m, 15m, 1h, 4h, 12h, 24h. Then dead-letter.
- Idempotency keys: customer can detect duplicate deliveries
- Webhook log + replay UI: customer can see failures + manually replay
- Test webhook UI: button in your dashboard to send sample payload
What NOT to expose publicly
- Internal user IDs (use UUIDs externally, sequential IDs internally)
- Internal admin endpoints
- Anything that exposes other customers' data via clever query
- Bulk export endpoints (rate-limit aggressively or move to async)
- Cost-expensive operations (AI inference, complex analytics) without billing model
For most SaaS we ship: webhook OUT from day 1, basic read API at month 6 (when first 5 enterprise customers ask), write API only if business model justifies. Documented with Mintlify or Scalar. SaaS builds →
Last reviewed: 27 April 2026.
Want this built for you?
Talk to Kashvi — 30-min call, honest assessment, no pitch deck.