API Development with Codex

You need to build a new API for managing team invitations. It requires five endpoints, input validation, auth middleware, rate limiting, database queries, email notifications, and comprehensive tests. The spec says “two days.” You could grind through it sequentially. Or you could plan the API in the IDE, scaffold the routes in a local thread, write tests in a parallel worktree, and have Codex generate the OpenAPI spec while you review the business logic.

What You’ll Walk Away With

• A parallel API development workflow: scaffold routes, write tests, and generate docs simultaneously
• Prompts for building endpoints with proper validation, error handling, and middleware
• Techniques for testing APIs in the Codex CLI with inline command execution
• A pattern for keeping OpenAPI specs in sync with implementation using automations

The Workflow

Step 1: Design the API Contract First

Start in the IDE extension or Codex App with a design prompt. Getting the API shape right before writing code prevents costly rework.

Tip

Copy-paste prompt for API design:

Design a REST API for team invitation management. Requirements:

- Create invitation (POST): send invite to email address with role assignment
- List invitations (GET): paginated, filterable by status (pending, accepted, expired)
- Resend invitation (POST): resend email for pending invitations
- Accept invitation (POST): accept via token (unauthenticated endpoint)
- Revoke invitation (PUT): cancel a pending invitation

For each endpoint, define:
1. HTTP method and path (following REST conventions)
2. Request body or query parameters with types
3. Response shape for success and each error case
4. Authentication requirements
5. Rate limiting rules

Output as an OpenAPI 3.1 YAML spec. Be opinionated about the design -- do not use generic placeholder names.

Review the spec and iterate before implementation. This becomes your contract.

Step 2: Scaffold Routes in a Local Thread

With the API contract defined, scaffold the actual endpoint handlers. Use Local mode for the initial scaffolding since you want the files in your working directory.

Tip

Copy-paste prompt for API scaffolding:

Implement the team invitation API based on the OpenAPI spec we just designed.

For each endpoint, create:
1. Route handler in src/routes/invitations/
2. Zod schema for request validation in src/routes/invitations/schemas.ts
3. Service function in src/services/invitations.ts for business logic
4. Database queries in src/lib/db/queries/invitations.ts using Drizzle ORM

Patterns to follow:
- Read existing routes in src/routes/ for handler patterns
- Use the auth middleware from src/middleware/auth.ts
- Use the validate middleware for Zod schema validation
- Return consistent error responses: { error: string, details?: object }
- Use structured logging, not console.log

Do NOT implement the email sending logic yet. Stub it with a TODO comment.
Do NOT write tests yet. We will do that in a separate worktree.

Run the type checker after implementation. Fix any type errors.

After Codex generates the files, review in the App’s review pane. Stage and commit the scaffolding before moving to parallel work.

Step 3: Write Tests in a Parallel Worktree

Create a Worktree thread based on the branch with your scaffolded routes. The test agent runs in complete isolation — it can run the test suite repeatedly without interfering with your local development.

Write comprehensive tests for the team invitation API endpoints:

Unit tests (tests/unit/services/invitations.test.ts):
- Test each service function with mocked database
- Cover validation logic: valid inputs, missing fields, invalid email formats, expired tokens
- Cover business logic: duplicate invitations, revoking accepted invitations, self-invitation prevention

Integration tests (tests/integration/invitations.test.ts):
- Test each endpoint with supertest against a real database
- Test authentication: valid token, missing token, insufficient permissions
- Test pagination: page size, offset, total count
- Test status filtering: pending only, accepted only, all
- Test rate limiting: exceed the limit and verify 429 response

Follow existing test patterns in tests/. Set up and tear down test data properly.
Run all tests after writing them. Fix any failures.

Step 4: Test Endpoints Interactively in the CLI

The CLI is excellent for rapid API testing because you can execute commands inline. Start Codex with your dev server running in another terminal:

codex

Then test your endpoints interactively:

The dev server is running on localhost:3000. Test the invitation API:

1. Create a test user and get an auth token
2. POST /api/invitations with a valid invitation
3. POST /api/invitations with the same email (should fail with duplicate error)
4. GET /api/invitations to list all invitations
5. POST /api/invitations/:id/resend for the pending invitation
6. Try accepting with an invalid token (should fail)

Use curl for each request and show me the responses. Flag anything unexpected.

The CLI executes curl commands directly and shows you the responses. This interactive testing catches issues that unit tests miss — middleware ordering, header requirements, response format inconsistencies.

Step 5: Generate OpenAPI Spec from Implementation

After the API is tested and working, generate (or update) the OpenAPI spec from the actual implementation:

Generate an OpenAPI 3.1 spec from the implemented invitation API routes in src/routes/invitations/.

Read the actual Zod schemas for request/response types.
Read the route handlers for HTTP methods, paths, and status codes.
Read the auth middleware for security scheme definitions.

Output as api/openapi.yaml. Include realistic examples in each endpoint.
Verify the spec is valid by checking the structure against the OpenAPI 3.1 standard.

Set up an automation to keep the spec in sync:

Compare the OpenAPI spec in api/openapi.yaml against the actual route handlers and Zod schemas in src/routes/. If any endpoints, parameters, or response shapes have changed since the spec was last generated, update the spec to match. If the spec is current, report that no changes are needed.

When This Breaks

Zod schemas and database schema drift apart. If you define Zod validation schemas separately from your Drizzle ORM schema, they can get out of sync. Tell Codex: “Derive Zod schemas from the Drizzle schema types where possible. Do not duplicate type definitions.”

Tests pass locally but fail in the worktree. This happens when the worktree’s database was not set up. Ensure your local environment setup script runs database migrations. Check the integrated terminal (Cmd + J) for setup script errors.

Rate limiting tests are flaky. Rate limit tests that depend on timing are inherently flaky. Tell Codex: “For rate limiting tests, send requests in a tight loop without delays, and verify the status code switches from 200 to 429 after the configured limit. Do not rely on time-based windows in tests.”

The generated OpenAPI spec does not match a specific consumer’s expectations. Codex generates the spec from your code, but your API consumers may expect different field names or response shapes. After generating, review the spec against your actual consumer requirements. Include consumer-specific constraints in your AGENTS.md review guidelines.

What’s Next

Database Operations with Codex Build the database layer that powers your API endpoints

Documentation Generation Generate comprehensive API documentation alongside your implementation