API Design Best Practices

One Booking, Many Systems

A travel website appears to offer one unified booking experience: you search for flights, hotels, and car rentals in one place. Behind that interface, however, the airline, hotel company, and car rental company each maintain their own computers, databases, and systems. The travel website coordinates these independent systems through web service calls rather than storing every organization's data in one central database.

Following a Search Request

The important design point is that this is a choreography of independent queries, not one query against one massive database. The travel website acts as an orchestrator: it knows which service to contact, sends the request, receives the result, and presents the combined information to the user.

Authoritative Data Ownership

In service-oriented architecture, each organization maintains a single authoritative copy of its own data in its own database. The airline owns flight data, the hotel owns room data, and the car rental company owns vehicle data. The travel website does not copy that data as its own inventory. Instead, it queries the owning service in real time.

Boundaries and Permissions

A service boundary is also a data-control boundary. The organization that owns the data decides which capabilities to expose through its web service. A hotel might allow the travel website to query available rooms and make reservations while withholding guest payment information and past booking history. The travel website can coordinate the permitted actions, but it does not receive unrestricted access to the hotel's database.

From Search to Payment

A completed travel booking is a sequence of calls, not a single database update. The travel website first coordinates search requests. When the user chooses an option, the website sends reservation requests to the relevant services. Each service updates its own database independently. Payment is then processed through a third system.

1. The traveler initiates a booking through the travel website.
2. The website sends search requests to the relevant airline, hotel, and car rental services.
3. Each service checks its own organization's data and returns an availability result.
4. The website sends reservation requests to the services for the options selected by the traveler.
5. Each service updates its own database independently when it processes its reservation.
6. The website coordinates payment processing through a third system.
7. The website presents the resulting booking information to the traveler.

Mistakes in Service Integration

• Treating the travel website as the owner of every organization's data.

  In SOA, each organization owns its own data and controls how other systems access it.

  Fix: Treat the travel website as an orchestrator that calls services controlled by the data-owning organizations.

• Maintaining a separate copy of another organization's live inventory.

  The copy can become inconsistent with the hotel's database and can cause the website to promise a room that has already been sold.

  Fix: Query the owning service in real time through its defined web service interface.

• Assuming a service exposes its entire database.

  Data owners decide what can be queried and what actions can be performed.

  Fix: Use only the capabilities and data that the owning organization exposes through its service.

• Describing a complete booking as one database transaction.

  A travel booking involves multiple web service calls, and each participating system updates its own database independently.

  Fix: Trace the booking as a coordinated sequence of searches, reservation requests, independent updates, and payment processing.

Practice the Trace

Practical Design Rules

• Keep each organization's authoritative data in the database controlled by that organization.
• Use web service calls to query live data instead of creating a competing copy of another organization's inventory.
• Let the data owner define what information is accessible and what actions another service can perform.
• Design the travel website as a coordinator that presents a unified interface while preserving independent service boundaries.
• Trace multi-service operations as a sequence of calls because searches, reservations, database updates, and payment processing involve different systems.