Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Yet another booking flows merge trial #33

Open
wants to merge 16 commits into
base: WIP-operator-complete-api-initial-version
Choose a base branch
from
Open

Yet another booking flows merge trial #33

Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
c35781e
Integrated booking by API
pierrecamilleri May 19, 2022
596bc9c
Remove PUT /bookings/{BookingId}
pierrecamilleri May 19, 2022
2d2a470
Booking ID as a UUID
pierrecamilleri May 19, 2022
0715a3a
Remove `passengerId` and `journeyId`
pierrecamilleri May 19, 2022
5399271
Remove operator / maas urls in connection message
pierrecamilleri May 19, 2022
7ab1c15
doc: UUID description
pierrecamilleri May 19, 2022
4bc3248
Compulsory long/lat/date in booking
pierrecamilleri May 30, 2022
6d3f49b
Remove Connection message - for now
pierrecamilleri May 30, 2022
a92bae2
Add `to` and `from` `User`s to POST /messages
pierrecamilleri May 30, 2022
8270140
Adding optional IDs to POST /messages
pierrecamilleri May 30, 2022
cb8f186
Add `operatorWebUrl` to `User`
pierrecamilleri May 30, 2022
88bb512
Extract `UserId` and rename `operatorWebUrl`
pierrecamilleri May 31, 2022
ca28065
Uppercase enum
pierrecamilleri May 31, 2022
4a5f068
Add message to PATCH /bookings
pierrecamilleri May 30, 2022
5d703c1
Correct `BookingAPI` description (with OpenAPI < 3.1.x)
pierrecamilleri May 30, 2022
52596b1
Yet another booking flows merge trial
May 31, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
286 changes: 263 additions & 23 deletions standard-covoiturage_openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -205,6 +205,192 @@ paths:
500:
$ref: '#/components/responses/InternalServerError'

/messages:
post:
tags:
- Interact
summary: Send a message to the owner of a retrieved journey.
description: Route used to allow a user to connect back to the owner of a retrieved journey through a texte message.
operationId: postConnections
requestBody:
content:
application/json:
schema:
type: object
required:
- from
- to
- message
- recipientCarpoolerType
properties:
from:
$ref: '#/components/schemas/UserId'
to:
$ref: '#/components/schemas/UserId'
message:
type: string
maxLength: 500
description: Free text content of a message. The message can contain all the details (phone number, email, etc.) allowing the recipient to call back the sender in order to carpool with him/her.
recipientCarpoolerType:
type: string
enum:
- DRIVER
- PASSENGER
default: DRIVER
description: Defines if the recipient of this message is either the driver or the passenger.
journeyId:
type: string
minLength: 1
maxLength: 255
description: ID of the journey to which the message is related (if any)
bookingId:
allOf:
- $ref: '#/components/schemas/bookingId'
description: ID of the booking to which the message is related (if any)

responses:
201:
description: Successful operation.
404:
description: The targeted journey or user no more exists.
400:
$ref: '#/components/responses/BadRequest'
401:
$ref: '#/components/responses/Unauthorized'
429:
$ref: '#/components/responses/TooManyRequests'
500:
$ref: '#/components/responses/InternalServerError'

/bookings:
post:
tags:
- Interact
summary: Create a punctual outward Booking request.
description: Route used to synchronize a Booking request initiated by a platform to the second platform involved in the shared punctual outward journey. While posting a new Booking, its status must always be set first as `status=WAITING_CONFIRMATION`. _Reminder:_ In case of booking without deeplink, the sender platform MUST also store the Booking object, and be ready to receive modifications of it through the PATCH /bookings API endpoint.
operationId: postBookings
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VersatileBookingRequest'

responses:
201:
description: Successful operation. A new Booking has been created.
content:
application/json:
schema:
$ref: '#/components/schemas/VersatileBookingRequest'
400:
$ref: '#/components/responses/BadRequest'
401:
$ref: '#/components/responses/Unauthorized'
429:
$ref: '#/components/responses/TooManyRequests'
500:
$ref: '#/components/responses/InternalServerError'

/bookings/{bookingId}:
patch:
tags:
- Interact
summary: Updates status of an existing Booking request.
description: Route used to update the status of an existing Booking request. Should be used usually just to confirm, cancel, etc. an existing Booking.
operationId: patchBookings
parameters:
- name: bookingId
in: path
required: true
schema:
$ref: '#/components/schemas/bookingId'
- name: status
description: New status of the Booking.
in: query
required: true
schema:
$ref: '#/components/schemas/bookingStatus'
- name: message
description: Free text content of a message. The message can contain explanations on the status change.
in: query
schema:
type: string
maxLength: 500

responses:
200:
description: Successful operation.
400:
$ref: '#/components/responses/BadRequest'
401:
$ref: '#/components/responses/Unauthorized'
429:
$ref: '#/components/responses/TooManyRequests'
500:
$ref: '#/components/responses/InternalServerError'
404:
description: The targeted journey, booking or user no more exists. Error code can be among `missing_journey, missing_booking, missing_user` .
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: |-
Explain why the request couldn't be processed.
409:
description: Conflict. This booking has already the new status requested. Error code is `status_already_set`.
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: |-
Explain why the request couldn't be processed.


get:
tags:
- Interact
summary: Retrieves an existing Booking request.
description: Route used to retrieve the details of an existing Booking request. Can only be used by the operator having created the Booking request. This route is provided to check if the Booking object state is similar between two operators, but its usage should be required to handle the full use case of a booking.
operationId: getBookings
parameters:
- name: bookingId
in: path
required: true
schema:
$ref: '#/components/schemas/bookingId'
responses:
200:
description: Successful operation.
content:
application/json:
schema:
$ref: '#/components/schemas/VersatileBookingRequest'
400:
$ref: '#/components/responses/BadRequest'
401:
$ref: '#/components/responses/Unauthorized'
429:
$ref: '#/components/responses/TooManyRequests'
500:
$ref: '#/components/responses/InternalServerError'
404:
description: This Booking object no more exists. Error code can be among `missing_journey, missing_booking, missing_user` .
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: |-
Explain why the request couldn't be processed.

/status:
get:
tags:
Expand Down Expand Up @@ -584,11 +770,9 @@ components:
- passengerDropLat
- passengerDropLng
- status
- webUrl
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If marked as optional here, it must be clear that it is mandatory for the booking events flow (#5).

properties:
id:
type: "string"
description: Unique identifier of the booking.
$ref: '#/components/schemas/bookingId'
passengerPickupDate:
type: number
description: Passenger pickup datetime as a UNIX UTC timestamp in seconds.
Expand Down Expand Up @@ -616,13 +800,7 @@ components:
type: string
description: String representing the drop-off address.
status:
type: string
enum:
- WAITING_CONFIRMATION
- CONFIRMED
- CANCELLED
- COMPLETED_PENDING_VALIDATION
- VALIDATED
$ref: '#/components/schemas/bookingStatus'
distance:
type: "integer"
description: |
Expand All @@ -641,9 +819,10 @@ components:
- type: object
required:
- passenger
- webUrl
properties:
passenger:
$ref: '#/components/schemas/User'
passengerId:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This change is not compatible with the booking events flow (#5) as the passenger / driver will not be known on MaaS's side.

$ref: '#/components/schemas/UserId'

DriverCarpoolBooking:
type: object
Expand All @@ -653,14 +832,50 @@ components:
required:
- driver
- price
- webUrl
properties:
driver:
$ref: '#/components/schemas/User'
driverId:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This change is not compatible with the bookings events flow (#5) as the passenger / driver will not be known on MaaS's side.

$ref: '#/components/schemas/UserId'
price:
$ref: '#/components/schemas/Price'
car:
$ref: '#/components/schemas/Car'

VersatileBookingRequest:
allOf:
- $ref: '#/components/schemas/CarpoolBooking'
type: object
required:
- passenger
- driverId
- priceId
properties:
passengerId:
$ref: '#/components/schemas/UserId'
driverId:
$ref: '#/components/schemas/UserId'
passengerJourneyId:
type: string
minLength: 1
maxLength: 255
description: ID of the passenger's journey to which the booking is related (if any)
driverJourneyId:
type: string
minLength: 1
maxLength: 255
description: ID of the driver's journey to which the booking is related (if any)
price:
$ref: '#/components/schemas/Price'
duration:
type: integer
description: Carpooling duration in seconds.
car:
$ref: '#/components/schemas/Car'
message:
type: string
maxLength: 500
description: Free text content of a message.

Price:
type: object
properties:
Expand All @@ -682,17 +897,10 @@ components:
description: ISO 4217 code representing the currency of the price.

User:
allOf:
- $ref: '#/components/schemas/UserId'
type: object
required:
- id
- alias
properties:
id:
type: string
description: User's unique identifier.
alias:
type: string
description: User's alias.
firstName:
type: string
description: User's first name.
Expand All @@ -718,6 +926,22 @@ components:
type: boolean
description: true if the identity of this user has been verified by the operator or a third party; and the firstName, lastName, birthdate have been confirmed as identitical to an official identity proof document. Can be left empty if the information is not available.

UserId:
type: object
required:
- id
- alias
- operator
properties:
id:
type: string
description: User's identifier. It MUST be unique for a given `operator`
operator:
type: string
description: The operator identifier. MUST be a Fully Qualified Domain Name (example carpool.mycity.com) owned by the operator or a Partially Qualified Domain Name (example operator.org) owned and exclusively operated by the operator. Operators SHOULD always send the same value.
alias:
type: string
description: User's alias

Preferences:
type: object
Expand Down Expand Up @@ -756,6 +980,22 @@ components:
type: string
description: Brand of the car.

bookingId:
type: string
format: uuid
description: Booking id is common between both operators, and must be created as a [UUID](https://datatracker.ietf.org/doc/html/rfc4122) by whoever initiates the booking. Usage of a [4 UUID](https://datatracker.ietf.org/doc/html/rfc4122#section-4.4) generation algorithm is advised.

bookingStatus:
type: string
description: Status of the booking.
enum:
- WAITING_CONFIRMATION
- CONFIRMED
- CANCELLED
- COMPLETED_PENDING_VALIDATION
- VALIDATED
default: WAITING_CONFIRMATION

responses:
BadRequest:
description: Bad Request. See error message.
Expand Down