API Design Best Practices

The important design point is that this is a choreography of independent queries, not one query against one massive database.

Programming

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.

How does one travel website coordinate requests across independent airline, hotel, and car rental systems?

Following a Search Request

Worked example

A Unified Vacation Search

A traveler enters search criteria on a travel website and expects flight, hotel, and car rental results in one place.

1
Start at the interface
The traveler submits search criteria to the travel website.
2
Query the airline
The travel website sends a web service request to the airline service for available flights.
3
Query the hotel
The travel website sends a web service request to the hotel service for available rooms.
4
Query the car rental service
The travel website sends a web service request to the car rental service for available vehicles.
5
Read each organization's database
Each service queries its own organization's database rather than a shared travel-site database.
6
Aggregate the results
The travel website receives the separate results, brings them together, and displays them through its single interface.

Result

The traveler sees one coordinated search experience even though multiple independent systems supplied the results.

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.

Which service owns each piece of reservation data, and how does another service access it without creating a conflicting duplicate?

Architecture choice	Who owns the inventory data?	What happens when data changes?
Service-oriented architecture	The organization that provides the service	The travel website queries the owning service rather than maintaining its own copy.
Monolithic alternative	One application owns flights, hotels, cars, payments, and user accounts	The single application updates its large database, but independent organizations lose direct control over their own data.

SOA preserves the autonomy of the organizations whose systems are being integrated.

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.

How do service boundaries determine which system can create, read, or modify customer, reservation, availability, and payment data?

Key point

Well-defined service interfaces allow organizations to cooperate without surrendering ownership. The airline, hotel, and car rental company each decide what the travel website can query and what actions it can perform.

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.

What happens next from booking initiation through availability checks, reservation confirmation, and payment processing?

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

Common mistake
Treating the travel website as the owner of every organization's data.
What it looks like
Assuming the travel website should own the airline's flight inventory, the hotel's room inventory, and the car rental company's vehicle inventory.
Why it fails
In SOA, each organization owns its own data and controls how other systems access it.
Do this instead
Treat the travel website as an orchestrator that calls services controlled by the data-owning organizations.
Common mistake
Maintaining a separate copy of another organization's live inventory.
What it looks like
Keeping a local copy of hotel room availability and using that copy as the booking authority.
Why it fails
The copy can become inconsistent with the hotel's database and can cause the website to promise a room that has already been sold.
Do this instead
Query the owning service in real time through its defined web service interface.
Common mistake
Assuming a service exposes its entire database.
What it looks like
Expecting the travel website to access all hotel guest payment information and past booking history.
Why it fails
Data owners decide what can be queried and what actions can be performed.
Do this instead
Use only the capabilities and data that the owning organization exposes through its service.
Common mistake
Describing a complete booking as one database transaction.
What it looks like
Assuming one travel-site database update can simultaneously complete airline, hotel, car rental, and payment work.
Why it fails
A travel booking involves multiple web service calls, and each participating system updates its own database independently.
Do this instead
Trace the booking as a coordinated sequence of searches, reservation requests, independent updates, and payment processing.

Practice the Trace

MEDIUM

A traveler searches for a flight and hotel through one travel website, selects both, and proceeds to pay. Describe which system should be queried for flight availability, which system should be queried for room availability, where the reservation updates occur, and which system handles payment processing.

Hints

Start by identifying the organization that owns each type of data.
Separate search calls from reservation requests.
Remember that the travel website coordinates the calls but does not own every database.

Your attempt (not saved)

Key point

A strong answer identifies the airline service as the source for flight availability, the hotel service as the source for room availability, the airline and hotel services as the systems that process their respective reservations and update their own databases, and a third system as the payment processor.

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.

Key Takeaways

Service-oriented architecture lets one travel website coordinate independent airline, hotel, and car rental systems through web service calls.
Each organization keeps one authoritative copy of its own data, while the travel website queries that data instead of maintaining a competing inventory copy.
Data owners control access through defined service interfaces and can limit both visible data and permitted actions.
A booking is a sequence of searches, reservation requests, independent database updates, and payment processing through a third system.
The travel website is an orchestrator and unified interface, not the owner of every participating organization's data.

Related concepts

More concepts starting with A