From 21469d145d147a09d35708f131d39aae46a5b308 Mon Sep 17 00:00:00 2001 From: Edwin van den Belt Date: Tue, 9 Apr 2024 16:54:45 +0200 Subject: [PATCH] 428-precondition-required --- TOMP-API.yaml | 402 ++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 376 insertions(+), 26 deletions(-) diff --git a/TOMP-API.yaml b/TOMP-API.yaml index ff86e11..a0ed3b9 100644 --- a/TOMP-API.yaml +++ b/TOMP-API.yaml @@ -4,7 +4,7 @@ info: description: An API between MaaS providers and transport operators for booking trips and corresponding assets.

The documentation (examples, process flows and sequence diagrams) can be found at github. - version: "1.4.1" + version: "1.5.0" license: name: Apache 2.0 url: "http://www.apache.org/licenses/LICENSE-2.0.html" @@ -252,6 +252,8 @@ paths: $ref: "#/components/responses/409Conflict" "410": $ref: "#/components/responses/410Gone" + "428": + $ref: "#/components/responses/428PreconditionRequired" get: description: Optional - Returns bookings that has been created earlier, selected on state. tags: @@ -260,9 +262,44 @@ paths: parameters: - name: state in: query - required: true + required: false schema: $ref: "#/components/schemas/bookingState" + - name: min-time + description: start time of the time window of all bookings (partially) overlapping with this time window + in: query + required: false + schema: + type: string + format: date-time + - name: max-time + description: end time of the time window of all bookings (partially) overlapping with this time window + in: query + required: false + schema: + type: string + format: date-time + - name: min-price + description: minimum search price, for the whole trip + in: query + required: false + schema: + type: number + format: float + - name: max-price + description: maximum search price, for the whole trip + in: query + required: false + schema: + type: number + format: float + - name: contains-asset-type + in: query + required: false + description: filter the bookings on the ID of the asset type. Should return all complete + bookings containing a leg executed with this asset type. + schema: + type: string responses: "200": @@ -322,6 +359,13 @@ paths: type: string format: One IETF BCP 47 (RFC 5646) language tag required: true + Expires: + description: The result is valid until this timestamp. The pending booking is expired after this timestamp. + schema: + description: A HTTP date string, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Expires + type: string + format: http-date + required: true "400": $ref: "#/components/responses/400BadRequest" "401": @@ -345,7 +389,11 @@ paths: schema: type: string post: - description: This endpoint **must** be used to alter the state of a booking:
- The operation 'CANCEL' Cancels the booking (see <4> in the process flow - booking),
- the operation 'EXPIRE' informs that the booking-option is expired (see <5> in the process flow - booking) and
- the 'COMMIT' actually makes this booking option a real confirmed booking. (see also (3.2) in process flow - booking). This event should also be used to commit in the 'postponed-commit' scenario.
- 'DENY' tells the MP that the leg is cancelled in the post-commit scenario.

`CANCEL` - Cancels a confirmed booking.
`EXPIRE` - Typically for sending back a signal from TO to MP to tell the pending state is expired. Expiring twice should return 204. Expiring a booking in a non-pending state will result in 403.
`COMMIT` - Turns the booking in a confirmed state, after all legs are in state pending. Committing twice will result in 204. If the booking is in state CANCELLED or EXPIRED, a commit will result a 403.
`DENY` - Used for the 'postponed-commit' scenario. Whenever a TO cannot give guarantees directly to fulfil a booking, it can return a 'COMMIT', but the state of the booking object should be 'POSTPONED-COMMIT'. In the conditions returned in the planning phase is stated until when this phase can be. After this time it will become expired. Otherwise, it can be committed when the leg is confirmed or denied (using this event). + description: This endpoint **must** be used to alter the state of a booking:
+ `CANCEL` - Cancels a confirmed booking.
+ `EXTEND_EXPIRY_TIME` - the MP request to extend the expiry time of the booking. Only available when the Process Identifier 'ALLOW_EXTEND_BOOKING_EXPIRY_TIME' is used. Whenever the extension is not granted, 410 should be returned.
+ `COMMIT` - Turns the booking in a confirmed state, after all legs are in state pending. If the booking is in state COMMITTED, CANCELLED or EXPIRED, a commit will result a 403.
+ `DENY` - Used for the 'postponed-commit' scenario. Whenever a TO cannot give guarantees directly to fulfil a booking, it can return a 'COMMIT', but the state of the booking object should be 'POSTPONED-COMMIT'. In the conditions returned in the planning phase is stated until when this phase can be. After this time it will become expired. Otherwise, it can be committed when the leg is confirmed or denied (using this event). tags: - booking - MP @@ -370,6 +418,13 @@ paths: type: string format: One IETF BCP 47 (RFC 5646) language tag required: true + Expires: + description: Mandatory whenever the EXTEND_EXPIRY_TIME is used. It must contain the updated expiry time + schema: + description: A HTTP date string, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Expires + type: string + format: http-date + required: false "400": $ref: "#/components/responses/400BadRequest" "401": @@ -1863,6 +1918,10 @@ components: - $ref: "#/components/schemas/conditionReturnArea" - $ref: "#/components/schemas/conditionUpfrontPayment" - $ref: "#/components/schemas/conditionRequireEvidence" + - $ref: "#/components/schemas/conditionRequireOnboardingSteps" + - $ref: "#/components/schemas/conditionRequireOffboardingSteps" + - $ref: "#/components/schemas/conditionRequirePausingSteps" + - $ref: "#/components/schemas/conditionRequireResumingSteps" discriminator: propertyName: conditionType @@ -2125,6 +2184,14 @@ components: description: The intended arrival time at the destination of the booking (over all legs) type: string format: date-time + actualDepartureTime: + description: the 'departureTime' can be used as 'plannedDepartureTime' whenever the trip has started. Use this field to ease searching for discrepances between planned and actual departure times + type: string + format: date-time + actualArrivalTime: + description: the 'arrivalTime' can be used as 'plannedArrivalTime' whenever the trip has ended. Use this field to ease searching for discrepances between planned and actual arrival times + type: string + format: date-time mainAssetType: description: the asset type that is used mainly in the complete trip. $ref: "#/components/schemas/assetType" @@ -2165,7 +2232,13 @@ components: properties: operation: type: string - enum: [CANCEL, EXPIRE, DENY, COMMIT] + description: the operation that is requested. When extra time is needed to complete the initial booking, EXTEND_EXPIRY_TIME can be used. + In the response there is the 'Expiry' header field to supply the new expiry timestamp. + enum: [CANCEL, DENY, COMMIT, EXTEND_EXPIRY_TIME] + extendReason: + type: string + description: in case `operation` is EXTEND_EXPIRY_TIME, the reason for extension must be supplied here. + enum: [BOOKING_PENDING, PAYMENT_PENDING, OTHER] origin: type: string description: This operation can be done on behalf of another party. The MP can act on behalf of the END_USER (cancel this booking for me); @@ -2217,6 +2290,31 @@ components: ] example: CONFIRMED + bookingStep: + type: object + allOf: + - $ref: "#/components/schemas/information" + - type: object + properties: + action: + type: string + description: The possible steps are described here
+ `PENDING` - to show whenever the booking is in PENDING state (not confirmed)
+ `WAITING` - to indicate that the TO is processing the booking, optionally after an extension of the expiry time
+ `WAITING_FOR_PAYMENT` - to indicate that the payment hasn't been settled, after an extension of the expiry time with reason payment
+ `CONFIRMED` - to show whenever the booking is in a COMMITTED state (confirmed)
+ `CANCELLED` - to show whenever the booking is cancelled
+ `CONDITIONAL_CONFIRMED` - to show whenever the booking is conditionally confirmed (see process identifiers)
+ `EXPIRED` - to show whenever the booking is expired (the expiry time has passed)
+ enum: [ + PENDING, + WAITING_FOR_PAYMENT, + CONFIRMED, + CONDITIONAL_CONFIRMED, + CANCELLED, + EXPIRED + ] + card: description: Any kind of card that isn't a license, only provide the cards that are required allOf: @@ -2345,6 +2443,8 @@ components: conditionRequireEvidence: description: use this condition to specify the evidence you require as TO in the off-boarding process. It can be used in addition with the static process identifier 'OFF_BOARDING_REQUIRED'. The evidence should be delivered in the /legs/{id}/events object (legEvent), in the `url` array + This construct is deprecated since v1.5. Please migrate it to conditionRequireOffboardingSteps + deprecated: true allOf: - $ref: "#/components/schemas/condition" - type: object @@ -2361,6 +2461,54 @@ components: CHARGING ] + conditionRequireOnboardingSteps: + allOf: + - $ref: "#/components/schemas/condition" + - type: object + required: + - steps + properties: + steps: + type: array + items: + $ref: "#/components/schemas/onBoardingStep" + + conditionRequireOffboardingSteps: + allOf: + - $ref: "#/components/schemas/condition" + - type: object + required: + - steps + properties: + steps: + type: array + items: + $ref: "#/components/schemas/offBoardingStep" + + conditionRequirePausingSteps: + allOf: + - $ref: "#/components/schemas/condition" + - type: object + required: + - steps + properties: + steps: + type: array + items: + $ref: "#/components/schemas/pausingStep" + + conditionRequireResumingSteps: + allOf: + - $ref: "#/components/schemas/condition" + - type: object + required: + - steps + properties: + steps: + type: array + items: + $ref: "#/components/schemas/resumingStep" + conditionReturnArea: description: a return area. In the condition list there can be multiple return area's. allOf: @@ -2631,7 +2779,7 @@ components: endpointImplementation: type: object - description: a complete endpoint description, containing all endpoints, their status, but also the served scenarios and implemented process flows. The identifiers for the process flows can be found at https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers + description: a complete endpoint description, containing all endpoints, their status, but also the served scenarios and implemented process flows. The identifiers for the process flows can be found at https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers
required: - version - baseUrl @@ -2653,6 +2801,38 @@ components: $ref: "#/components/schemas/scenario" processIdentifiers: $ref: "#/components/schemas/processIdentifiers" + steps: + type: object + description: The steps can be specified here, when they are uniform over all assets. If some assets should be handled differently, it can be specified as a condition in the booking for that specific asset(type). + properties: + planning: + type: array + items: + $ref: "#/components/schemas/planningStep" + booking: + type: array + items: + $ref: "#/components/schemas/bookingStep" + onboarding: + type: array + description: this array should be considered as a sequence! + items: + $ref: "#/components/schemas/onBoardingStep" + offboarding: + type: array + description: this array should be considered as a sequence! + items: + $ref: "#/components/schemas/offBoardingStep" + pausing: + type: array + description: this array should be considered as a sequence! + items: + $ref: "#/components/schemas/pausingStep" + resuming: + type: array + description: this array should be considered as a sequence! + items: + $ref: "#/components/schemas/resumingStep" error: type: object @@ -2799,6 +2979,11 @@ components: example: 11.00 format: float minimum: 0 + assetState: + description: in case the fare is dependent on being in use or being paused, this field must be used. Default IN_USE + type: string + enum: [ "IN_USE", "PAUSED" ] + default: "IN_USE" meta: type: object additionalProperties: true @@ -2864,16 +3049,20 @@ components: type: description: the type of the information provided type: string - enum: [URL, IMAGE] + enum: [URL, IMAGE, PLAIN_TEXT, HTML] url: - description: the internet location of the information + description: the internet location of the information, used in case or type `URL` or `IMAGE` type: string goal: description: the purpose of the information type: string enum: [INSTRUCTIONS, SALES] + text: + type: string + description: free format text or HTML, depending on the type. Not to use in combination with `URL` or `IMAGE` showTime: description: the moment when the information must be displayed + deprecated: true type: string enum: [PLANNING, COMMITTED_BOOKING, PREPARE, SET_IN_USE, PAUSE, OPEN_TRUNK, START_FINISHING, FINISH] @@ -2972,11 +3161,19 @@ components: description: The destination of this leg, using this asset type $ref: "#/components/schemas/place" departureTime: - description: The departure time of this leg + description: The departure time of this leg. Or, in case of a parking, the start of the usage. type: string format: date-time arrivalTime: - description: The intended arrival time at the to place + description: The intended arrival time at the to place. Or, in case of a parking, the end of the usage. + type: string + format: date-time + actualArrivalTime: + description: the 'arrivalTime' can be used as 'plannedArrivalTime' whenever the leg has ended. Use this field to ease searching for discrepances between planned and actual arrival times + type: string + format: date-time + actualDepartureTime: + description: the 'departureTime' can be used as 'plannedDepartureTime' whenever the leg has started. Use this field to ease searching for discrepances between planned and actual departure times type: string format: date-time travelerReferenceNumbers: @@ -3010,6 +3207,10 @@ components: - $ref: "#/components/schemas/conditionReturnArea" - $ref: "#/components/schemas/conditionUpfrontPayment" - $ref: "#/components/schemas/conditionRequireEvidence" + - $ref: "#/components/schemas/conditionRequireOnboardingSteps" + - $ref: "#/components/schemas/conditionRequireOffboardingSteps" + - $ref: "#/components/schemas/conditionRequirePausingSteps" + - $ref: "#/components/schemas/conditionRequireResumingSteps" discriminator: propertyName: conditionType state: @@ -3033,10 +3234,10 @@ components: description: Array of data to open a specific asset (e.g. QR code, image base64) $ref: "#/components/schemas/tokenArray" userCommunication: - description: Additional information a TO can send to a customer (instructions, sales info, ...) - type: array - items: - $ref: "#/components/schemas/information" + description: Additional information a TO can send to a customer (instructions, sales info, ...) + type: array + items: + $ref: "#/components/schemas/information" memo: type: string @@ -3089,6 +3290,8 @@ components: $ref: "#/components/schemas/duration" distance: $ref: "#/components/schemas/distance" + asset: + $ref: "#/components/schemas/asset" legState: type: string @@ -3164,6 +3367,83 @@ components: description: whenever the booking contains multiple legs, this field is mandatory and contain the id of the leg related to the notification. + offBoardingStep: + type: object + allOf: + - $ref: "#/components/schemas/information" + - type: object + properties: + action: + type: string + description: these actions are available
+ `SEND_START_FINISHING` - the TO needs to be informed the leg is about to finish
+ `PARK_ASSIST` - user action to park (stop) using the asset
+ `UNLOCK_LOCKER` - user action, could be triggered by the START_FINISH event
+ `CONNECT_CHARGER` - user action
+ `LOCK_ASSET` - user action, could be triggered by the FINISH event
+ `SEND_OPEN_TRUNK` - the TO opens the trunk remotely
+ `UNLOCK_TRUNK` - user action
+ `STOW_HELMET` - user action
+ `LOCK_TRUNK` - user action
+ `LOCK_LOCKER` - user action
+ `SEND_FINISH` - the TO wants to be informed about the end of the leg
+ `SEND_EVIDENCE_PARKED` - the TO requires parking evidence
+ `SEND_EVIDENCE_HELMET` - the TO requires evidence of storing the helmet
+ `SEND_EVIDENCE_CHARGER` - the TO requires evidence of correct usage of the charger + enum: [ + SEND_START_FINISHING, + PARK_ASSIST, + UNLOCK_LOCKER, + CONNECT_CHARGER, + LOCK_ASSET, + SEND_OPEN_TRUNK, + UNLOCK_TRUNK, + STOW_HELMET, + LOCK_TRUNK, + LOCK_LOCKER, + SEND_FINISH, + SEND_EVIDENCE_PARKED, + SEND_EVIDENCE_HELMET, + SEND_EVIDENCE_CHARGER + ] + + onBoardingStep: + type: object + allOf: + - $ref: "#/components/schemas/information" + - type: object + properties: + action: + type: string + description: + The possible steps are described here
+ `SEND_PREPARE` - indicate the leg is going to start
+ `UNLOCK_LOCKER` - user action - optionally triggered by the PREPARE event
+ `DISCONNECT_CHARGER` - requested user action
+ `SHOW_DAMAGES` - show known damages to end user
+ `UNLOCK_ASSET` - requested user action or triggered by SET_IN_USE event
+ `START_ASSET` - requested user action
+ `SEND_OPEN_TRUNK` - request TO to open trunk/helmet case remotely
+ `UNLOCK_TRUNK` - requested user action
+ `TAKE_HELMET` - requested user action
+ `SEND_SET_IN_USE` - request to start leg
+ `SEND_ASSIGN_ASSET` - request to assign the specified asset to the leg
+ `LOCK_LOCKER` - requested user action + enum: [ + SEND_PREPARE, + UNLOCK_LOCKER, + DISCONNECT_CHARGER, + SHOW_DAMAGES, + UNLOCK_ASSET, + START_ASSET, + SEND_OPEN_TRUNK, + UNLOCK_TRUNK, + TAKE_HELMET, + SEND_SET_IN_USE, + SEND_ASSIGN_ASSET, + LOCK_LOCKER + ] + oneStopBookingRequest: type: object anyOf: @@ -3176,6 +3456,37 @@ components: customer: description: The user that wants to make this booking, only to supply when requested in the conditionRequireBookingData $ref: "#/components/schemas/customer" + callbackUrl: + description: The callback URL of the Maas Provider, to use as base url for callback, f.x. the POST legs/{id}/events and POST /bookings/{id}/events. Only to be provided + when this deviates from standard or agreed URL. + type: string + format: URL + + pausingStep: + type: object + allOf: + - $ref: "#/components/schemas/information" + - type: object + properties: + action: + type: string + description: allowed actions
+ `SEND_PAUSE` - send leg event PAUSE to inform the TO
+ `PARK_ASSIST` - user action, the end user can be informed how and where to park
+ `LOCK_ASSET` - user action, can be triggered by the PAUSE event
+ `SEND_OPEN_TRUNK` - request TO to open the trunk remotely
+ `UNLOCK_TRUNK` - user action
+ `STOW_HELMET` - user action
+ `LOCK_TRUNK` - user action + enum: [ + SEND_PAUSE, + PARK_ASSIST, + LOCK_ASSET, + SEND_OPEN_TRUNK, + UNLOCK_TRUNK, + STOW_HELMET, + LOCK_TRUNK + ] phone: type: object @@ -3282,6 +3593,20 @@ components: type: object additionalProperties: true + planningStep: + type: object + description: this action allows to publish advertisements together with the proposed leg. + allOf: + - $ref: "#/components/schemas/information" + - type: object + properties: + action: + type: string + description: the `RESULT_SHOWN` action requires the MP to display some information to the customer when it is viewing the proposed legs. + enum: [ + RESULT_SHOWN + ] + planning: description: A travel planning with bookable options that fulfil the constraints of the planning type: object @@ -3388,6 +3713,32 @@ components: items: $ref: "#/components/schemas/requirement" + resumingStep: + type: object + allOf: + - $ref: "#/components/schemas/information" + - type: object + properties: + action: + type: string + description: possible values
+ `UNLOCK_ASSET` - user action, could be triggered by SET_IN_USE event
+ `SEND_OPEN_TRUNK` - request TO to open trunk remotely
+ `UNLOCK_TRUNK` - user action
+ `TAKE_HELMET` - user action
+ `LOCK_TRUNK` - user action
+ `START_ASSET` - user action
+ `SEND_SET_IN_USE` - the TO wants to be informed that the leg is resumed. Optionally triggers the unlock of the vehicle + enum: [ + UNLOCK_ASSET, + SEND_OPEN_TRUNK, + UNLOCK_TRUNK, + TAKE_HELMET, + LOCK_TRUNK, + START_ASSET, + SEND_SET_IN_USE + ] + scenario: type: string enum: [ @@ -3473,33 +3824,27 @@ components: description: the total capacity of this station type: integer assetTypeCapacity: - type: array + type: object description: An object used to describe the docking capacity of a station where each key is a reference to the ID of the assetType, and the value is a number representing the total docking points installed at this station, both available and unavailable for the specified vehicle type. - items: - type: object - additionalProperties: true + additionalProperties: true example: { "child-bike-01": 3, "general-bike": 18 } assetsAvailable: type: integer description: the number of available assets in this station (total) assetTypesAvailable: - type: array + type: object description: An object used to describe the available assets of a station where each key is a reference to the ID of the assetType, and the value is a number representing the total available asset of this type at this station. - items: - type: object - additionalProperties: true + additionalProperties: true example: { "child-bike-01": 1, "general-bike": 3 } docksAvailable: type: integer description: the number of free docks assetDocksAvailable: - type: array + type: object description: An object used to describe the free slots of a station where each key is a reference to the ID of the assetType, and the value is a number representing the total free docks for this assetType at this station. - items: - type: object - additionalProperties: true + additionalProperties: true example: { "child-bike-01": 1, "general-bike": 3 } @@ -4216,6 +4561,11 @@ components: description: The requested resources does not exist or the requester is not authorized to see it or know it exists. 409Conflict: description: The request will not be fulfilled. The request itself is legal, but the content conflicts with the server and might be stale. The user might try again after looking up the current state of the resource. - 410Gone: description: The requested resource is no longer available. This is permanent. + 428PreconditionRequired: + description: Preconditions are not met in order to access the requested resource. This might happen e.g. if a booking is made but the user has been blocked by the TO. See https://github.com/TOMP-WG/TOMP-API/wiki/Error-handling-in-TOMP for further explanation of error code. + content: + application/json: + schema: + $ref: "#/components/schemas/error"