rest-api design patterns

TRAVELERS

POST /travelers

DELETE /travelers/<id>

GET /travelers[/<id>]

PUT /travelers/<id>

TRAVELERS

POST /travelers



PUT /travelers/<id>

TRAVELERS

POST /travelers



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>



GET /tickets/<id>



TICKETS

PUT /tickets/<id>



GET /tickets/<id>



TRAVELERS

PUT /travelers/<id>


DELETE /trips/<id>/travelers

GET /travelers/id>

GET /trips/<id>/travelers

POST /trips/<id>/travelers

TRAVELERS

PUT /travelers/<id>



GET /travelers/id>



TRAVELERS

PUT /travelers/<id>



GET /travelers/id>



*

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


TRAVELERS


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/<id>

TRAVELERS



TRAVELERS



TRIPS

DELETE /trips/<id>

TRIPS

DELETE /trips/<id>

TRIPS

DELETE /trips/<id>

*

1

*

1

TRAVELERS


GET /trips/<id>/travelers/<id>

TRAVELERS



TRAVELERS



TRIPS

GET /trips/<id>

TRIPS

GET /trips/<id>

TRIPS

GET /trips/<id>

*

1

*

1

TRAVELERS

PUT /trips/<id>/travelers/<id>

TRAVELERS


TRAVELERS


TRIPS

PUT /trips/<id>

TRIPS

PUT /trips/<id>

TRIPS

PUT /trips/<id>

*

1

*

1

TRAVELERS



TRAVELERS



TRAVELERS



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/<id>

TICKETS



TICKETS



*

1

*

1

TRAIN-TICKETS

POST /tickets/trains

PUT /tickets/trains/<id>

TRAIN-TICKETS



TRAIN-TICKETS



TICKETS


GET /tickets

GET /tickets/<id>

TICKETS


GET /tickets

GET /tickets/<id>

TICKETS


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



AIRPLANE-TICKETS



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: [email protected]

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. R

EFIN

E

TRAVELERS

POST /travelers



PUT /travelers/<id>

TRAVELERS

POST /travelers



PUT /travelers/<id>

TRAVELERS

POST /travelers



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

rest-api design patterns

Engineering