REST-API ENDPOINT DESIGN PATTERNS

GUIDELINE: REFLECT RELATIONSHIPS IN ENDPOINT PATHS

1. VISUALIZE THE LOGICAL DATAMODEL 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.
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 AGGREGATION-PATTERN (INDEPENDENT LIFECYCLES)
INHERITANCE-PATTERN
• USE WHEN INSTANCES OF BOTH TYPES IN A RELATIONSHIP CAN EXIST INDEPENDENT OF EACH OTHER
TYPES INCLUDING VOLATILE TYPES SUCH AS CALCULATED RESULTS. REDUCES THE NUMBER OF ENDPOINTS.
• PUT THE ENDPOINTS OF BOTH TYPES IN THEIR OWN NAMESPACE/PATH.
• 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.

TICKETS
TRAVELERS TRIPS

POST /travelers
* POST /trips
TICKETS
DELETE /travelers/<id> DELETE /trips/<id> TRAIN-TICKETS
GET /travelers[/<id>]
* GET /trips[/<id>]
DELETE /tickets/<id>
PUT /travelers/<id> PUT /trips/<id> POST /tickets/trains
* GET /tickets
PUT /tickets/trains/<id>
GET /tickets/<id>

TRIPS
TRAVELERS TRIPS

POST /travelers
* POST /trips
DELETE /travelers/<id> DELETE /trips/<id> AIRPLANE-TICKETS
GET /travelers[/<id>]
0..1 GET /trips[/<id>]
PUT /travelers/<id> PUT /trips/<id> POST /tickets/airplanes
1 PUT /tickets/airplanes/<id>
1

TRAVELERS
*
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

2. ASSIGN ENDPOINTS TO TYPES

EACH TYPE GETS ITS OWN SET OF APPROPRIATE HTTP-METHODS (POST, PUT, PATCH, DELETE, GET) AND PATHS. TRAVELERS TRIPS
*
ESSENTIALLY CONVERTING THE DATAMODEL INTO A CLASS-MODEL. USE THE GUIDELINES ON THE RIGHT TO POST /trips/<id>/travelers POST /trips
1
DETERMINE THE MOST NATURAL ENDPOINT PATHS.

TICKETS
TRIPS
TRAVELERS
PUT /tickets/<id> *
DELETE /tickets/<id> DELETE /trips/<id>
DELETE /trips/<id>/travelers
DELETE /trips/<id>/travelers/<id>/tickets DELETE /trips/<id>/travelers/<id>
1
GET /tickets/<id>
GET /trips/<id>/travelers/<id>/tickets
POST /trips/<id>/travelers/<id>/tickets

TRAVELERS TRIPS
* TRIPS *
GET /trips/<id>/travelers GET /trips/<id>
PUT /trips/<id> GET /trips/<id>/travelers/<id> 1
POST /trips
GET /trips
GET /trips/<id>
DELETE /trips/<id>

TRAVELERS TRIPS
1 1
*
PUT /trips/<id>/travelers/<id> PUT /trips/<id>
1
TRAVELERS
4. REFINE

PUT /travelers/<id>
DELETE /travelers/<id>
*
DELETE /trips/<id>/travelers
GET /travelers/id> TICKETS TRAVELERS TRIPS
GET /trips/<id>/travelers * *
POST /trips/<id>/travelers GET /trips/<id>/travelers/<id>/tickets GET /trips/<id>/travelers GET /trips
GET /trips/<id>/travelers/<id>/tickets/<id> 1 GET /trips/<id>/travelers/<id> 1 GET /trips/<id>

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.

Created by: patrick.savalle@nn-group.com