Definition #

An API (Application Programming Interface) is a contract that lets one piece of software request data or trigger actions from another. In the Don't Do It stack, APIs sit behind every integration point-whether you are pulling analytics, triggering automations, or exposing product features to partners.

What it guarantees #

• Shape: The request and response follow a documented schema, so consumers know exactly what to send and expect back.
• Auth: Access is gated through Supabase auth, service tokens, or signed requests to make sure the caller is trusted.
• Versioning: Changes are introduced deliberately (usually with a /v1, /v2 style path) so existing consumers do not break unexpectedly.

When to reach for it #

Scenario	API usage	Notes
Connect a front-end view to Supabase	REST or RPC endpoint	Use React Query to cache and handle loading states.
Trigger internal workflows	Edge function or webhook	Sign calls with the Supabase service role.
Let partners integrate	Public REST or GraphQL endpoint	Provide docs, rate limits, and API keys via the Access Console.

Example request #

GET /api/v1/projects/{projectId}/reports
Authorization: Bearer <access-token>
Accept: application/json

{
	"projectId": "8d7c66ad-0ba4-45b8-be4d-e5925fa2b4c5",
	"reports": [
		{
			"id": "report-001",
			"type": "weekly_snapshot",
			"generated_at": "2024-12-10T14:32:00Z"
		}
	]
}

Related terms #

• Endpoint – The URL + method pair that exposes a specific capability.
• SDK – A language-specific toolkit that wraps raw API calls to reduce boilerplate.
• Rate limiting – Rules that cap how many requests a consumer can make within a time window.

Further reading #

• Internal style guide: /docs/api-style-guide
• Supabase REST reference: https://supabase.com/docs/guides/database/rest
• RFC: 2024-11-api-versioning-strategy