The document outlines various REST API endpoint designs for managing travelers, trips, and tickets, detailing the HTTP methods associated with each. It discusses patterns such as aggregation and composition for structuring endpoints based on relationships between resources. Additionally, it emphasizes the importance of aligning endpoint paths with logical data models and process steps to enhance usability and efficiency.

1. TRAVELERS
POST /travelers
DELETE /travelers/<id>
GET /travelers[/<id>]
PUT /travelers/<id>
TRAVELERS
POST /travelers
DELETE /travelers/<id>
GET /travelers[/<id>]
PUT /travelers/<id>
TRAVELERS
POST /travelers
DELETE /travelers/<id>
GET /travelers[/<id>]
PUT /travelers/<id>
TRIPS
POST /trips
DELETE /trips/<id>
GET /trips[/<id>]
PUT /trips/<id>
TRIPS
POST /trips
DELETE /trips/<id>
GET /trips[/<id>]
PUT /trips/<id>
TRIPS
POST /trips
DELETE /trips/<id>
GET /trips[/<id>]
PUT /trips/<id>
*
*
*
*
TICKETS
PUT /tickets/<id>
DELETE /tickets/<id>
DELETE /trips/<id>/travelers/<id>/tickets
GET /tickets/<id>
GET /trips/<id>/travelers/<id>/tickets
POST /trips/<id>/travelers/<id>/tickets
TICKETS
PUT /tickets/<id>
DELETE /tickets/<id>
DELETE /trips/<id>/travelers/<id>/tickets
GET /tickets/<id>
GET /trips/<id>/travelers/<id>/tickets
POST /trips/<id>/travelers/<id>/tickets
TICKETS
PUT /tickets/<id>
DELETE /tickets/<id>
DELETE /trips/<id>/travelers/<id>/tickets
GET /tickets/<id>
GET /trips/<id>/travelers/<id>/tickets
POST /trips/<id>/travelers/<id>/tickets
TRAVELERS
PUT /travelers/<id>
DELETE /travelers/<id>
DELETE /trips/<id>/travelers
GET /travelers/id>
GET /trips/<id>/travelers
POST /trips/<id>/travelers
TRAVELERS
PUT /travelers/<id>
DELETE /travelers/<id>
DELETE /trips/<id>/travelers
GET /travelers/id>
GET /trips/<id>/travelers
POST /trips/<id>/travelers
TRAVELERS
PUT /travelers/<id>
DELETE /travelers/<id>
DELETE /trips/<id>/travelers
GET /travelers/id>
GET /trips/<id>/travelers
POST /trips/<id>/travelers
*
1
*
1
TRIPS
PUT /trips/<id>
POST /trips
GET /trips
GET /trips/<id>
DELETE /trips/<id>
TRIPS
PUT /trips/<id>
POST /trips
GET /trips
GET /trips/<id>
DELETE /trips/<id>
TRIPS
PUT /trips/<id>
POST /trips
GET /trips
GET /trips/<id>
DELETE /trips/<id>
*
1
*
1
TRAVELERS
POST /trips/<id>/travelers
TRAVELERS
POST /trips/<id>/travelers
TRAVELERS
POST /trips/<id>/travelers
TRIPS
POST /trips
TRIPS
POST /trips
TRIPS
POST /trips
*
1
*
1
AGGREGATION-PATTERN (INDEPENDENT LIFECYCLES)
• USE WHEN INSTANCES OF BOTH TYPES IN A RELATIONSHIP CAN EXIST INDEPENDENT OF EACH OTHER
• PUT THE ENDPOINTS OF BOTH TYPES IN THEIR OWN NAMESPACE/PATH.
COMPOSITION-PATTERN (DEPENDENT LIFECYCLES / WHOLE-PART RELATIONSHIP)
REFLECT WHOLE-PART RELATIONSHIPS / HIERARCHY IN THE PATH OF AN ENDPOINT TO REFLECT THE RIGHT SEQUENCE IN WHICH
TO RETRIEVE AND MANIPULATE RESOURCES.
• USE WHEN INSTANCES OF ONE TYPE (E.G. TRAVELER) CANNOT EXIST INDEPENDENT OF INSTANCES OF OTHER TYPE (E.G. TRIP
• PREPEND THE ENDPOINTS OF THE DEPENDENT TYPE (TYPE TRAVELERS IN THIS EXAMPLE) WITH THE OTHER TYPE S PATH
TRAVELERS
DELETE /trips/<id>/travelers
DELETE /trips/<id>/travelers/<id>
TRAVELERS
DELETE /trips/<id>/travelers
DELETE /trips/<id>/travelers/<id>
TRAVELERS
DELETE /trips/<id>/travelers
DELETE /trips/<id>/travelers/<id>
TRIPS
DELETE /trips/<id>
TRIPS
DELETE /trips/<id>
TRIPS
DELETE /trips/<id>
*
1
*
1
TRAVELERS
GET /trips/<id>/travelers
GET /trips/<id>/travelers/<id>
TRAVELERS
GET /trips/<id>/travelers
GET /trips/<id>/travelers/<id>
TRAVELERS
GET /trips/<id>/travelers
GET /trips/<id>/travelers/<id>
TRIPS
GET /trips/<id>
TRIPS
GET /trips/<id>
TRIPS
GET /trips/<id>
*
1
*
1
TRAVELERS
PUT /trips/<id>/travelers/<id>
TRAVELERS
PUT /trips/<id>/travelers/<id>
TRAVELERS
PUT /trips/<id>/travelers/<id>
TRIPS
PUT /trips/<id>
TRIPS
PUT /trips/<id>
TRIPS
PUT /trips/<id>
*
1
*
1
TRAVELERS
GET /trips/<id>/travelers
GET /trips/<id>/travelers/<id>
TRAVELERS
GET /trips/<id>/travelers
GET /trips/<id>/travelers/<id>
TRAVELERS
GET /trips/<id>/travelers
GET /trips/<id>/travelers/<id>
TRIPS
GET /trips
GET /trips/<id>
TRIPS
GET /trips
GET /trips/<id>
TRIPS
GET /trips
GET /trips/<id>
*
1
*
1
TICKETS
GET /trips/<id>/travelers/<id>/tickets
GET /trips/<id>/travelers/<id>/tickets/<id>
TICKETS
GET /trips/<id>/travelers/<id>/tickets
GET /trips/<id>/travelers/<id>/tickets/<id>
TICKETS
GET /trips/<id>/travelers/<id>/tickets
GET /trips/<id>/travelers/<id>/tickets/<id>
*
1
*
1
TRAIN-TICKETS
POST /tickets/trains
PUT /tickets/trains/<id>
TRAIN-TICKETS
POST /tickets/trains
PUT /tickets/trains/<id>
TRAIN-TICKETS
POST /tickets/trains
PUT /tickets/trains/<id>
TICKETS
DELETE /tickets/<id>
GET /tickets
GET /tickets/<id>
TICKETS
DELETE /tickets/<id>
GET /tickets
GET /tickets/<id>
TICKETS
DELETE /tickets/<id>
GET /tickets
GET /tickets/<id>
INHERITANCE-PATTERN
REDUCES THE NUMBER OF ENDPOINTS.
• PUT THE POST, PUT AND PATCH METHODS IN SUBTYPES
• PUT THE DELETE AND GET METHODS IN THE SUPER TYPE.
• WILL ONLY WORK IF AL INSTANCES HAVE UNIQUE ID S ACROSS THE HIERARCHY.
AIRPLANE-TICKETS
POST /tickets/airplanes
PUT /tickets/airplanes/<id>
AIRPLANE-TICKETS
POST /tickets/airplanes
PUT /tickets/airplanes/<id>
AIRPLANE-TICKETS
POST /tickets/airplanes
PUT /tickets/airplanes/<id>
1. VISUALIZE THE LOGICAL DATAMODEL
CREATE THE CUSTOMER FACING LOGICAL DATAMODEL. AVOID STRICT 3NF-NORMALIZATION, N:M
RELATIONSHIPS ARE ALLOWED. USE ASSOCIATION AND INHERITANCE. BE VERY STRICT WITH THE
MULTIPLICITIES ON BOTH ENDS OF THE ASSOCIATIONS. MODEL NOT ONLY PERSISTENT TYPES BUT ALL
TYPES INCLUDING VOLATILE TYPES SUCH AS CALCULATED RESULTS.
REST-API ENDPOINT DESIGN PATTERNS
Created by: patrick.savalle@nn-group.com
2. ASSIGN ENDPOINTS TO TYPES
EACH TYPE GETS ITS OWN SET OF APPROPRIATE HTTP-METHODS (POST, PUT, PATCH, DELETE, GET) AND PATHS.
ESSENTIALLY CONVERTING THE DATAMODEL INTO A CLASS-MODEL. USE THE GUIDELINES ON THE RIGHT TO
DETERMINE THE MOST NATURAL ENDPOINT PATHS.
GUIDELINE: REFLECT RELATIONSHIPS IN ENDPOINT PATHS
DEPENDING ON THE TYPE OF ASSOCIATION BETWEEN TYPES (AGGREGATION VS. COMPOSITION) PREPEND THE PATHS OF PARTS WITH THE
PATHS OF THEIR WHOLES DEPENDENT PARTS SHOULD GENERALLY BE ACCESSED THROUGH THE WHOLE.
TICKETSTICKETSTICKETS
TRAVELERSTRAVELERSTRAVELERS
*
1
*
1
TRIPSTRIPSTRIPS
*
1
*
1
3. MATCH THE ENDPOINTS TO PROCESS STEPS
DRAW BPMN2 DIAGRAMS FOR A REPRESENTATIVE SET OF SCENARIO S AND RUN THEM AGAINST THE API.
A GOOD API SHOULD HAVE ITS ENDPOINTS CORRESPOND TO INDIVIDUAL PROCESS STEPS, ALMOST ONE-
ON-ONE.
4.REFINE
TRAVELERS
POST /travelers
DELETE /travelers/<id>
GET /travelers[/<id>]
PUT /travelers/<id>
TRAVELERS
POST /travelers
DELETE /travelers/<id>
GET /travelers[/<id>]
PUT /travelers/<id>
TRAVELERS
POST /travelers
DELETE /travelers/<id>
GET /travelers[/<id>]
PUT /travelers/<id>
TRIPS
POST /trips
DELETE /trips/<id>
GET /trips[/<id>]
PUT /trips/<id>
TRIPS
POST /trips
DELETE /trips/<id>
GET /trips[/<id>]
PUT /trips/<id>
TRIPS
POST /trips
DELETE /trips/<id>
GET /trips[/<id>]
PUT /trips/<id>
*
0..1
*
0..1