API Development

DevStride auto-generates a fully typed frontend API client and OpenAPI documentation from backend route definitions. This ensures the frontend SDK always matches the backend API — no manual sync needed.

Generating the API Client

ds api generate-api-client

What It Does

1. Scans all Hono route definitions in the backend
2. Generates an OpenAPI 3.1.0 specification from route metadata
3. Produces a class-based TypeScript SDK in frontend/src/api/
4. Formats the output with Prettier

The generated SDK provides:

• Fully typed request and response objects
• Method signatures matching each API endpoint
• Compile-time safety — the frontend won't build if the SDK is out of sync with the backend

When to Run

Run ds api generate-api-client after:

• Adding a new API endpoint
• Changing a route path
• Modifying request body or response types
• Adding or removing query parameters
• Deleting an endpoint

Excluding Routes

Add x-skip-client metadata to routes that shouldn't appear in the frontend SDK (e.g., internal healthcheck endpoints, webhook receivers):

// In your Hono route definition
app.get('/healthcheck', { 'x-skip-client': true }, (c) => {
  return c.json({ status: 'ok' });
});

Generating API Documentation

ds api generate-api-docs

What It Does

Generates a comprehensive OpenAPI 3.0.0 specification at:

backend/src/modules/api/interface-adapters/lambda/http/openapi.json

The generated spec includes:

• All public API endpoints with descriptions
• Authentication methods
• Request/response schemas
• Example curl commands
• Troubleshooting guides

Excluding Routes from Documentation

Two exclusion levels are available:

Use x-skip for internal endpoints that developers need to call programmatically but shouldn't be in public docs. Use x-skip-client for endpoints that the frontend never calls (webhooks, healthchecks).

Backend-to-Frontend Call Flow

Understanding how a frontend API call reaches the backend helps when debugging:

Frontend SDK call
    → HTTP request to API Gateway
    → Lambda handler (Hono route)
    → Input validation
    → Command/Query constructed
    → CommandBus/QueryBus.execute()
    → Service handler (business logic)
    → Repository (database access)
    → Result<T, E> returned
    → Response formatted and sent

The code generators (ds local generate command/query) scaffold this entire chain. The API client generator ensures the frontend matches the entry point.

Next Steps

• Local Development — Running and testing locally
• Developer Lifecycle — End-to-end workflow examples