REST-API design patterns
•
4 likes•1,282 views
How to design a good REST-API. The explanation video is here: https://www.youtube.com/watch?v=_ABoZ3C4BMk
Report
Share
![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](https://cdn.statically.io/img/image.slidesharecdn.com/rest-api-design-patterns-171224134729/85/REST-API-design-patterns-1-320.jpg)
REST-API design patterns
- 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