Message

openapi: 3.0.
3
info:
title: YumYumNow Delivery Microservice API
description: APIs for managing deliveries.
version: 1.0.0
tags:
- name: Delivery
description: Operations related to deliveries
- name: Restaurant
description: Operations related to restaurants
- name: Error
description: Operations related to unexpected events during delivery
- name: Analytics
description: Operations related to statistics
paths:
/deliveries:
post:
tags:
- Delivery
summary: Add Delivery entity
requestBody:
description: Request body for creating a new Delivery entity
content:
application/json:
schema:
type: object
properties:
orderID:
type: string
description: ID of the order for the delivery
status:
type: string
description: Status of the delivery
deliveryAddress:
type: string
description: Address for the delivery
vendorID:
type: string
description: ID of the vendor associated with the delivery
required:
- orderID
- status
- deliveryAddress
- vendorID
description: Create a new Delivery entity and persist in the database
responses:
'201':
description: Delivery added successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Delivery'
'400':
description: Bad Request. Missing or invalid parameters.
content:
application/json:
schema:
type: string
description: Code indicating a bad request
example: "BAD_REQUEST"
'404':
description: Not Found. The specified order or vendor ID does not exist.
content:
application/json:
schema:
type: string
description: Code indicating a not found error
example: "NOT_FOUND"
'422':
description: Unprocessable Entity. Invalid data or validation errors.
content:
application/json:
schema:
type: string
description: Code indicating unprocessable entity
example: "UNPROCESSABLE_ENTITY"
'500':
description: Server error
/deliveries/{deliveryID}:
get:
summary: Retrieve a specific Delivery entity
description: Returns fields of Delivery entity visible to your User role. You
must specify the Delivery id and your User id.
tags:
- Delivery
parameters:
- name: deliveryID
in: path
description: ID of the Delivery entity
required: true
schema:
type: string
format: uuid
- name: userID
in: header
description: User ID for authorization
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
'400':
description: Bad Request. Invalid input format or missing parameters.
content:
application/json:
schema:
type: string
'401':
description: Unauthorized access
content:
application/json:
schema:
type: string
description: Code indicating unauthorized access
example: "UNAUTHORIZED"
'404':
description: Delivery not found
content:
application/json:
schema:
type: string
description: Code indicating delivery not found
example: "DELIVERY_NOT_FOUND"
'500':
content:
application/json:
schema:
type: string
description: Code indicating server error
example: "SERVER_ERROR"
put:
tags:
- Delivery
summary: Update Delivery entity
description: Update fields of Delivery entity visible to your user role
parameters:
- name: deliveryID
in: path
required: true
schema:
type: string
format: uuid
- name: userID
in: header
required: true
schema:
type: string
format: uuid
requestBody:
description: Update delivery
content:
application/json:
schema:
required: true
responses:
'200':
description: Update successful
content:
application/json:
schema:
'400':
content:
application/json:
schema:
type: string
'401':
content:
application/json:
schema:
type: string
'404':
content:
application/json:
schema:
type: string
'500':
content:
application/json:
schema:
type: string
/deliveries/{deliveryId}/status:
put:
tags:
- Delivery
summary: Update status of Delivery entity
description: Update status of Delivery entity visible to your user role
parameters:
- $ref: '#/components/parameters/DeliveryId'
- $ref: '#/components/parameters/UserId'
requestBody:
description: Update status of delivery
content:
application/json:
schema:
$ref: '#/components/schemas/DeliveryStatus'
responses:
'200':
description: Status update successful
content:
application/json:
schema:
'400':
content:
application/json:
schema:
type: string
'401':
description: Unauthorized access.
content:
application/json:
schema:
type: string
'403':
description: Forbidden. User lacks necessary permissions. Only admins,
vendors and couriers are allowed to update the status of an order.
content:
application/json:
schema:
type: string
description: Code indicating forbidden access due to lack of
permissions
example: "FORBIDDEN"
'404':
content:
application/json:
schema:
type: string
'500':
content:
application/json:
schema:
type: string
/restaurants:
post:
tags:
- Restaurant
summary: Add Restaurant entity
requestBody:
description: Request body for creating a new Restaurant entity. This is an
internal endpoint that ensures consistency among microservices. Should be called by
others when creating a restaurant.
content:
application/json:
schema:
type: object
properties:
restaurantID:
type: string
description: ID of the order for the restaurant
location:
type: array
minItems: 2
maxItems: 2
items:
type: string
description: Address for the deliver
required:
- orderID
- status
- deliveryAddress
- vendorID
description: Create a new Restaurant entity and persist in the database
responses:
'201':
description: Restaurant added successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Restaurant'
'400':
description: Bad Request. Missing or invalid parameters.
content:
application/json:
schema:
type: string
'500':
/restaurants/{restaurantID}:
get:
summary: Retrieve a specific Restaurant entity
tags:
- Restaurant
parameters:
- name: restaurantID
in: path
description: ID of the Restaurant entity
required: true
schema:
type: string
format: uuid
- name: userID
in: header
required: true
schema:
type: string
description: Returns a restaurant by ID
responses:
'200':
description: Successful response
content:
application/json:
schema:
'400':
content:
application/json:
schema:
type: string
'401':
content:
application/json:
schema:
type: string
'404':
description: Restaurant not found
content:
application/json:
schema:
type: string
description: Code indicating restaurant not found
example: "RESTAURANT_NOT_FOUND"
'500':
content:
application/json:
schema:
type: string
delete:
summary: Delete a specific Restaurant entity
tags:
- Restaurant
description: Deletes a restaurant by ID. This is an internal endpoint that
ensures consistency among microservices. Should be called by others when deleting a
restaurant.
parameters:
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Deletion successful
content:
application/json:
schema:
type: string
description: Code indicating whether deletion was successful
example: "DELETION_SUCCESSFUL"
'400':
content:
application/json:
schema:
type: string
'404':
content:
application/json:
schema:
type: string
'500':
content:
application/json:
schema:
type: string
/restaurants/{restaurantId}/couriers:
put:
tags:
- Restaurant
summary: Set preferred set of couriers of Restaurant entity
description: If a restaurant wants to use only a specific subset of couriers,
they might be set by the admin or the vendor
parameters:
- $ref: "#/components/parameters/RestaurantId"
- $ref: "#/components/parameters/UserId"
requestBody:
description: Put a preferred set of couriers for the restaurant
required: true
content:
application/json:
schema:
type: object
properties:
preferredCouriers:
type: array
format: set
items:
type: string
format: uuid
description: List of IDs of couriers
responses:
'200':
description: Courier update successful
content:
application/json:
schema:
'400':
content:
application/json:
schema:
type: string
'401':
content:
application/json:
schema:
type: string
'403':
description: Forbidden. User lacks necessary permissions. Only admins and
vendors can set preferred couriers.
content:
application/json:
schema:
type: string
permissions
'404':
content:
application/json:
schema:
type: string
'500':
content:
application/json:
schema:
type: string
/admin/default-delivery-zone:
put:
tags:
- Restaurant
summary: Set delivery zone
description: Set delivery zone. Admin sets the zone of all restaurants, while
Vendor sets the zone of their only corresponding restaurant.
parameters:
- $ref: "#/components/parameters/UserId"
requestBody:
description: Set delivery zone of restaurant by ID
required: true
content:
application/json:
schema:
type: number
description: Radius of delivery zone
responses:
'200':
description: Delivery zone update successful
content:
application/json:
schema:
'400':
content:
application/json:
schema:
type: string
'401':
content:
application/json:
schema:
type: string
'403':
description: Forbidden. User lacks necessary permissions. Only admins and
vendors can update the delivery zone.
content:
application/json:
schema:
type: string
permissions
'404':
content:
application/json:
schema:
type: string
'500':
content:
application/json:
schema:
type: string
/restaurants/{restaurantID}/location:
put:
tags:
- Restaurant
summary: Update the location of Restaurant entity
description: Admin and vendor can update the location of a given restaurant.
This is an internal endpoint that ensures consistency. Should be called by other
microservices when updating the location of a restaurant.
parameters:
in: path
required: true
schema:
type: string
format: uuid
requestBody:
description: Location
content:
application/json:
schema:
type: array
minItems: 2
maxItems: 2
items:
type: number
format: double
description: An array of latitude and longitude
required: true
responses:
'200':
description: Location update successful
content:
application/json:
schema:
'404':
content:
application/json:
schema:
type: string
'400':
content:
application/json:
schema:
type: string
'500':
content:
application/json:
schema:
type: string
/errors/{deliveryId}:
get:
summary: Retrieve unexpected event for a specific Delivery entity
tags:
- Error
description: Returns an unexpected event associated with a Delivery by ID
parameters:
responses:
'200':
description: Successfully returned unexpected event
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized access. The provided user ID is not authorized
for this operation.
content:
application/json:
schema:
type: string
'404':
description: Delivery not found. There doesn't exist an Error with the
given ID.
content:
application/json:
schema:
type: string
'500':
content:
application/json:
schema:
type: string
post:
tags:
- Error
summary: Update unexpected event of Delivery entity
description: Update unexpected event of Delivery by ID
parameters:
requestBody:
description: Update unexpected event of delivery
content:
application/json:
schema:
required: true
responses:
'200':
description: Delivery error updated successfully
content:
application/json:
schema:
'400':
description: Bad Request. Invalid or missing parameters.
content:
application/json:
schema:
type: string
'401':
description: Unauthorized access. The provided user is not authorized for
this operation.
content:
application/json:
schema:
type: string
'404':
description: Error not found. There doesn't exist an Error with the given
ID.
content:
application/json:
schema:
type: string
'500':
content:
application/json:
schema:
type: string
/statistics/deliveries-per-hour:
get:
summary: Shows the number of deliveries per hour
tags:
- Analytics
description: Gets all deliveries and counts them depending on the hour of
delivery, then returns an array of size 24 containing the corresponding count of
deliveries
parameters:
- name: userId
in: header
schema:
type: string
responses:
'200':
description: Successfully computed statistic
content:
application/json:
schema:
type: array
items:
type: integer
example: [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16,
17, 18, 19, 20, 21, 22, 23, 24 ]
description: An array representing the count of deliveries for each
hour (0-23).
'401':
content:
application/json:
schema:
type: string
'403':
description: Forbidden. User lacks necessary permissions. Only admins
have access to analytics.
content:
application/json:
schema:
type: string
permissions
/statistics/driver-efficiency:
get:
summary: Shows what is the average delay for a given courier
tags:
- Analytics
description: For the specified period, gets the actual time of delivery and
divides by the estimated time of arrival to obtain a ratio; then, finds the average
of those ratios. This gives an approximation of how late the courier is on average.
parameters:
- name: userId
in: query
schema:
type: string
format: uuid
- name: startTime
in: query
schema:
$ref: "#/components/schemas/LocalDateTime"
- name: endTime
in: query
schema:
responses:
'200':
content:
application/json:
schema:
type: number
format: double
example: 1.0
description: The average delay ratio for the specified courier and
time period.
'400':
content:
application/json:
schema:
type: string
'401':
content:
application/json:
schema:
type: string
'403':
content:
application/json:
schema:
type: string
permissions
'404':
description: Courier Not Found. The specified courierID does not exist.
content:
application/json:
schema:
type: string
description: Code indicating courier not found
example: "COURIER_NOT_FOUND"
/statistics/success-rate:
get:
summary: Show percentage of successfully delivered orders
tags:
- Analytics
description: For the specified period, find the ratio of orders with status
delivered to all orders
parameters:
- name: userId
in: query
schema:
type: string
format: uuid
- name: startTime
in: query
schema:
- name: endTime
in: query
schema:
responses:
'200':
content:
application/json:
schema:
type: number
format: double
example: 75.0
description: The percentage of successfully delivered orders.
'400':
content:
application/json:
schema:
type: string
'401':
content:
application/json:
schema:
type: string
'403':
content:
application/json:
schema:
type: string
permissions
/statistics/unexpected-event-rate:
get:
summary: Shows what is the rate of a given unexpected event occurring for a
particular time period
tags:
- Analytics
description: For the specified period, gets the deliveries having a specified
unexpected event enum type and finds their ratio with all deliveries.
parameters:
- name: userID
in: query
required: false
schema:
type: string
- name: startTime
in: query
required: false
description: Start time with format YYYY-MM-DD HH:mm
schema:
type: string
example: "2023-11-19 18:20"
- name: endTime
in: query
required: false
description: End time with format YYYY-MM-DD HH:mm
schema:
type: string
example: "2023-11-19 18:20"
- name: unexpectedEvent
in: query
required: false
description: Enum type of the unexpected event
schema:
$ref: '#/components/schemas/ErrorType'
responses:
'200':
content:
application/json:
schema:
type: number
format: double
example: 10.0
description: The rate of the specified unexpected event for the
given time period.
'400':
content:
application/json:
schema:
type: string
'401':
content:
application/json:
schema:
type: string
'403':
content:
application/json:
schema:
type: string
permissions
'404':
description: Type Not Found. The specified unexpected event type does not
exist.
content:
application/json:
schema:
type: string
description: Code indicating unexpected event type not found
example: "TYPE_NOT_FOUND"
components:
parameters:
DeliveryId:
name: deliveryId
in: path
required: true
schema:
type: string
format: uuid
UserId:
name: userId
in: header
required: true
schema:
type: string
format: uuid
RestaurantId:
name: restaurantId
in: path
required: true
schema:
type: string
format: uuid
schemas:
Delivery:
type: object
properties:
deliveryID:
type: string
format: uuid
description: Unique identifier for the Delivery (will be the same as
orderID)
courierID:
type: string
format: uuid
description: Unique identifier for the Courier assigned to the Delivery
(will be taken from the Courier entity)
restaurantID:
type: string
format: uuid
description: Unique identifier for the restaurant making the Delivery.
estimatedPrepTime:
type: integer
format: minutes
description: Estimated time to cook/prepare the order
unexpectedEvent:
status:
$ref: "#/components/schemas/DeliveryStatus"
pickup_time:
type: string
format: date-time
description: Pick-up time in YYYY-MM-DD HH:mm format
example: "2023-11-19 18:20"
delivered_time:
type: string
format: date-time
description: Delivered time in YYYY-MM-DD HH:mm format
example: "2023-11-19 18:20"
deliveryAddress:
type: array
minItems: 2
maxItems: 2
items:
type: number
format: double
description: Latitude and longitude of the location the delivery is going
to
currentLocation:
type: array
minItems: 2
maxItems: 2
items:
type: number
format: double
description: Latitude and longitude of the current location of the
delivery
rating:
type: integer
description: Rating of the delivery from 1 - 5 provided by the customer.
DeliveryStatus:
type: string
description: Updates on where the order is on its journey
enum:
- PENDING
- ACCEPTED
- REJECTED
- PREPARING
- GIVEN_TO_COURIER
- ON_TRANSIT
- DELIVERED
Error:
type: object
properties:
errorID:
type: string
format: uuid
description: Unique identifier for the problem associated with the
Delivery (will be the same as deliveryID)
reason:
type: string
description: Reason (provided by courier) for problems with delivery
type:
$ref: "#/components/schemas/ErrorType"
ErrorType:
type: string
description: Type of problem with delivery (i.e., cancellation/delay). Can be
scaled later. Potentially, delayed deliveries will also have a specified numeric
delay.
enum:
- DELAYED
- CANCELLED
- OTHER
Restaurant:
type: object
properties:
restaurantID:
type: string
format: uuid
description: Unique identifier for the restaurant
couriers:
type: array
items:
type: string
format: uuid
description: List of couriers the restaurant prefers
location:
type: array
minItems: 2
maxItems: 2
items:
type: number
description: Longitude and latitude of the restaurant
deliveryZone:
type: number
description: Radius of the delivery zone
LocalDateTime:
type: string
description: Date and time
format: YYYY-MM-DD HH:mm
example: "2023-11-19 18:20"

Message

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Message

Uploaded by

Copyright:

Available Formats

openapi: 3.0.

You might also like