Api Design For Vibe Coders

An API (Application Programming Interface) is the contract between your frontend and your backend (or between your application and another application). It describes:

ENDPOINTS. URLs that do things. Each endpoint has a method (GET to read, POST to create, PUT/PATCH to update, DELETE to remove) and a path (/api/customers/123).

REQUEST FORMAT. What the client sends.

• URL parameters: /api/customers/123 (the 123 is a parameter).
• Query string: /api/customers?status=active (filters).
• Request body: for POST/PUT, the actual data being sent (usually JSON).
• Headers: metadata, including the auth token.

RESPONSE FORMAT. What the server sends back.

• Status code: 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Server Error.
• Body: JSON usually. Either the requested data or an error object.

AUTH. How the client proves who it is. Usually a JWT (JSON Web Token) or a session cookie sent in headers.

RATE LIMITS. How many requests a client can make per minute. Defends against abuse and runaway scripts.

For each endpoint, describe:

Method: GET / POST / PUT / DELETE Path: /api/... Auth required: yes/no, which roles Inputs: parameters, query, body schema Outputs: success body schema, error cases Side effects: what gets created/updated/deleted, what events fire, what emails go out

A worked example:

### POST /api/customers

Create a new customer.

Auth: Required. Roles: owner, office_staff.
Rate limit: 60/minute per user.

Request body:
```json
{
    "name": "string, required, 1-200 chars",
    "email": "string, required, valid email format",
    "phone": "string, optional, E.164 format",
    "address": {
        "street": "string, required",
        "city": "string, required",
        "state": "string, required, 2 chars",
        "zip": "string, required, 5 or 9 digits"
    },
    "notes": "string, optional, max 5000 chars"
}

Success: 201 Created

{
    "id": 123,
    "name": "...",
    "email": "...",
    "created_at": "2026-04-27T10:00:00Z"
}

Errors:

• 400: Validation error (returns field-level errors).
• 401: Not authenticated.
• 403: Authenticated but lacks permission.
• 409: Email already exists for another customer.

Side effects:

• Creates a row in customers table.
• Sends a "welcome" email to the customer (template: customer_welcome).
• Logs an event in audit_log with action='customer.created', actor=current_user_id.

This is what an API spec looks like. Five to fifty endpoints like this
make up a small business app. The agent reads them and implements them.

The shortcut: if your backend is mostly "read and write rows from a
database," use Devii (section 3.5). Devii generates this kind of API
automatically from your database schema. You skip the API design step
entirely.

The non-shortcut: if you have custom logic, use FastAPI and write the
specs above. The agent generates the FastAPI code. You review it.



================================================================================
PART 6 — VERIFICATION AND SAFETY
================================================================================