API Design Principles for an AI Travel Platform

The API returns `{ error: "something went wrong" }`. Three engineers spend two hours figuring out what actually went wrong. The frontend developer doesn't know if the error is retryable. The mobile developer doesn't know which field caused the validation failure. The backend developer doesn't know which code path produced the error.

This happened to us early on. It was the catalyst for establishing API conventions that we now enforce across every endpoint. Conventions feel like overhead when you're moving fast, but they're the thing that keeps a growing API surface understandable.

Standardized response format

Every API response follows the same structure. Success responses return `{ success: true, data: T }`. Error responses return `{ success: false, error: { code, message } }`.

The `success` boolean is the first thing any client checks. It's unambiguous. True means the operation worked. False means it didn't. No need to check HTTP status codes (which are also set correctly, but the body is the primary contract).

The `data` field contains the response payload, typed differently per endpoint. A trip list returns `{ success: true, data: Trip[] }`. A booking creation returns `{ success: true, data: Booking }`. The type varies, but the wrapper is always the same.

The `error` object has a machine-readable `code` (like `BOOKING_EXPIRED` or `PAYMENT_DECLINED`) and a human-readable `message` (like "The fare expired while processing your booking. Please search again for current prices"). The code is what client code switches on. The message is what gets displayed to users or logged for debugging.

This standardization means every client (mobile app, web app, internal tools) uses the same response parsing logic. When we add a new endpoint, the client team doesn't need to figure out a new response format.

Error codes that help

Our error codes are namespaced by domain: `AUTH_TOKEN_EXPIRED`, `BOOKING_ALREADY_CONFIRMED`, `PAYMENT_INSUFFICIENT_FUNDS`, `AGENT_TOOL_TIMEOUT`. The namespace tells you which system produced the error without reading the message.

Each error code has documentation: what it means, when it occurs, whether the request is retryable, and what the client should do. `AGENT_TOOL_TIMEOUT` is retryable (the external API might work on the next try). `BOOKING_ALREADY_CONFIRMED` is not retryable (the booking was already completed successfully). `PAYMENT_INSUFFICIENT_FUNDS` requires user action (try a different card).

The error message is intended for display or logging, not for parsing. Client code should never check if the message contains a specific string. That's what the code is for. Messages can change for clarity without breaking clients.

API versioning

Our API uses versioning middleware. The current version is included in the request path or headers, and the middleware routes to the appropriate handler.

Versioning lets us evolve the API without breaking existing clients. When we need to change a response format or modify an endpoint's behavior, we introduce a new version while maintaining the old one. Mobile apps that haven't updated yet continue working against the old version. New builds use the new version.

We're conservative about versioning. Not every change needs a version bump. Additive changes (adding a new field to a response, adding a new optional parameter) are backward compatible and don't require a new version. Breaking changes (removing a field, changing a field's type, altering behavior) do.

The goal is to have at most two active versions at any time. Supporting many versions creates maintenance burden. We deprecate old versions with clear timelines and enforce minimum app versions for mobile clients.

Type sharing between frontend and backend

Our a single typed language across the stack types for API contracts are defined in a shared types file and imported by both the backend (to ensure the API produces the right shapes) and the frontend (to ensure the client expects the right shapes).

This type sharing catches contract mismatches at build time. If the backend changes the Trip type to include a new required field, and the frontend doesn't account for it, the a single typed language across the stack compiler flags it. The alternative, discovering the mismatch at runtime when a mobile user gets a crash, is much more expensive.

The shared types include all the major entities: Trip, Booking, FlightOption, HotelOption, User, ChatMessage, and their related types. The API client on the frontend is typed against these, so autocomplete and type checking work through the entire call chain.

Endpoint design patterns

Our endpoints follow consistent patterns.

Resource CRUD follows standard REST conventions. `GET /trips` lists trips. `POST /trips` creates a trip. `GET /trips/:id` fetches one. `PUT /trips/:id` updates one.

Action endpoints use verbs. `POST /booking/trips/:id/book` initiates a booking. `POST /agent/process-message` processes an AI chat message. These don't fit the CRUD pattern, and we don't force them into it.

Health endpoints live at predictable paths. `GET /health` for deep health, `GET /health/live` for liveness. Every service exposes these at the same paths.

Webhook endpoints are separate from the main API surface. They have their own authentication (signature verification instead of signed session tokens), their own rate limits, and their own monitoring.

API design review

Every new endpoint goes through API design review before implementation. The review checks: Does the response follow the standard format? Are the error codes appropriate? Is the endpoint naming consistent with existing endpoints? Is it backward compatible with existing clients? Are the rate limits appropriate?

This review catches inconsistencies before they ship. Without it, each developer's endpoint would follow slightly different conventions, and the API surface would gradually become incoherent.

The review is lightweight. It's a checklist, not a committee. But it prevents the kind of drift that makes an API feel like it was built by twelve different people who never talked to each other.

Nowah is an AI travel agent that searches and books real flights and hotels through conversation — no filters, no thirty open tabs. Plan your next trip.