From f60c504aa93ee7439a6e467b4ce5e840ac1d8784 Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Wed, 27 Jun 2018 15:58:18 +0300 Subject: [PATCH 01/19] Start with MaaS API (originally by MaaS Global) Co-authored-by: laurisvan Co-authored-by: Feijk --- booking.yaml | 529 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 529 insertions(+) create mode 100644 booking.yaml diff --git a/booking.yaml b/booking.yaml new file mode 100644 index 0000000..102399e --- /dev/null +++ b/booking.yaml @@ -0,0 +1,529 @@ +openapi: 3.0.0 +servers: [] +info: + version: v1 + title: MaaS-TSP + description: > + This is a API specification of REST endpoints that a Transport Service + Provider (TSP) should implement to receive messages from MaaS. It is written + in machine readable [Swagger](http://swagger.io/) format, so thatAPI + endpoints, validators and test clients can be generated from the + documentation. + + + In addition to this documentation, MaaS maintains a [reference + implementation (**TODO**)](https://github.com/maasglobal/maas-tsp-api) with + test cases. It is also running as a [reference service + (**TODO**)](https://tsp.maas.global/). + + + Right now MaaS TSP API consists of the Booking API. In addition, a need for + customer feedback API (for mediating customer feedback to a TSP) and + administration API (for changing API keys etc.) may be defined. + termsOfService: 'http://api.maas.global/terms/' + contact: + name: MaaS API Team + email: developers@maas.fi + url: 'http://maas.fi/' + license: + name: MIT + url: 'http://opensource.org/licenses/MIT' +tags: + - name: Booking + description: >- + Booking related APIs are the core of a TSP implementation. + Correspondingly, a Booking is the main object exchanged between MaaS and a + TSP. + externalDocs: + description: Booking scenarios + url: 'https://github.com/maasglobal/maas-tsp-api/blob/master/specs/Booking.md' + - name: Listing + description: >- + Before a booking can be made via a TSP, available options at a given + location can be listed as follows + - name: TODO Feedback + description: >- + In order to receive customer feedback through MaaS, TSP may implement + these APIs. + - name: TODO Admin + description: >- + In the future MaaS will implement machine-readable APIs that a TSP may use + to update GTFS route information, API keys and other information that is + needed for communicating between MaaS and a TSP. +security: + - key: [] +paths: + /bookings/options/: + get: + description: >- + Returns available transport options for given coordinates. Start time + can be defined, but is optional. If startTime is not provided, but + required by the third party API, a default value of "Date.now()" is + used. + tags: + - Listing + parameters: + - name: from + description: 'User''s location in comma separated form e.g. 60.123,27.456' + in: query + required: true + schema: + type: string + pattern: >- + ^[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)$ + - name: to + description: 'A desired destination e.g. 60.123,27.456' + in: query + required: false + schema: + type: string + pattern: >- + ^[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)$ + responses: + '200': + description: >- + Available transport methods matching the given query parameters. If + no transport methods are available, an empty array is returned. + content: + application/json: + schema: + name: options + type: array + description: Available transport options for the queried TSP + items: + $ref: '#/components/schemas/options' + '400': + description: >- + If coordinates given in the request are invalid the server returns + 400 Bad request as a response. + content: + application/json: + schema: + $ref: '#/components/schemas/error' + /bookings/: + get: + description: Returns the `Booking` that has been created earlier + tags: + - Booking + parameters: + - name: state + description: The state the booking to fetch + in: query + required: true + schema: + type: string + format: >- + enum - BOOKED - CANCELLED - PAID - UPDATE_REQUESTED - UPDATED - + STARTED - FINISHED + responses: + '200': + description: The bookings matching the query + content: + application/json: + schema: + type: array + description: The bookings that matched the query (zero or more) + minItems: 0 + items: + $ref: '#/components/schemas/booking' + '400': + description: Bad request (invalid query parameters) + content: + application/json: + schema: + $ref: '#/components/schemas/error' + '401': + description: Authorization error (invalid API key) + content: + application/json: + schema: + $ref: '#/components/schemas/error' + default: + description: unexpected error + content: + application/json: + schema: + $ref: '#/components/schemas/error' + x-serverless-endpoint: echo~GET + post: + description: >- + Creates a new `Booking` for the TSP in **booked** state. The returned + object will be a refrence that is passed back & forth throughout the + booking life cycle. + + The Booking may be modified in the response, e.g. location being + adjusted for a more suitable pick-up location. + + In addition, the service may contain a **meta** attribute for arbitrary + TSP metadata that the TSP needs later, and **token** attribute depicting + how long the current state is valid. + tags: + - Booking + responses: + '200': + description: A new booking was succesfully created + content: + application/json: + schema: + $ref: '#/components/schemas/booking' + '400': + description: Bad request (invalid body parameters) + content: + application/json: + schema: + $ref: '#/components/schemas/error' + '401': + description: Authorization error (invalid API key) + content: + application/json: + schema: + $ref: '#/components/schemas/error' + default: + description: Unexpected error + content: + application/json: + schema: + $ref: '#/components/schemas/error' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/newBooking' + description: New `Booking` data + required: true + parameters: [] + '/bookings/{id}': + get: + description: Returns the `Bookings` that have been created through the system. + tags: + - Booking + parameters: + - name: id + in: path + description: Booking identifier + required: true + schema: + type: string + responses: + '200': + description: The booking was found + content: + application/json: + schema: + $ref: '#/components/schemas/booking' + '400': + description: Bad request (invalid query or body parameters) + content: + application/json: + schema: + $ref: '#/components/schemas/error' + '401': + description: Authorization error (invalid API key) + content: + application/json: + schema: + $ref: '#/components/schemas/error' + '404': + description: The booking was not found + content: + application/json: + schema: + $ref: '#/components/schemas/error' + default: + description: Unexpected error + content: + application/json: + schema: + $ref: '#/components/schemas/error' + put: + description: >- + Modifies the state of a `Booking`, e.g. **cancels**, **pays** or + **reschedules** it. The previous booking information is passed forward + as-is for reference. + tags: + - Booking + parameters: + - name: id + in: path + description: Booking identifier + required: true + schema: + type: string + responses: + '200': + description: The booking was modified + content: + application/json: + schema: + $ref: '#/components/schemas/booking' + default: + description: Unexpected error + content: + application/json: + schema: + $ref: '#/components/schemas/error' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/booking' + description: New `Booking` data + required: true +components: + securitySchemes: + key: + description: > + MaaS can authenticate using an access token as part of the HTTP(S) + headers. The keys are sent as part of every request that MaaS makes to + the TSP API with a `x-api-key` custom header option. + type: apiKey + name: X-Api-Key + in: header + schemas: + error: + type: object + description: >- + An error that the service may send, e.g. in case of invalid input, + missing authorization or internal service error. + required: + - message + - code + properties: + message: + type: string + description: A human readable error message (preferrably in English) + code: + type: string + description: 'A TSP internal error code, used for reference' + newBooking: + type: object + description: 'A new booking, created by MaaS POST request in ''new'' state' + required: + - leg + - customer + properties: + state: + type: string + description: The state of the booking (always new for new bookings) + enum: + - NEW + leg: + $ref: '#/components/schemas/leg' + customer: + $ref: '#/components/schemas/customer' + booking: + type: object + description: >- + The booking information describing the state and details of the + transaction + allOf: + - $ref: '#/components/schemas/newBooking' + properties: + id: + description: The identifier MaaS will be using to referring to the booking + type: string + state: + $ref: '#/components/schemas/bookingState' + terms: + $ref: '#/components/schemas/bookingState' + token: + $ref: '#/components/schemas/token' + meta: + description: Arbitrary metadata that a TSP can add + type: object + required: + - id + - state + - leg + - customer + - token + bookingState: + description: The life-cycle state of the booking (from NEW to FINISHED) + type: string + enum: + - NEW + - BOOKED + - CANCELLED + - PAID + - UPDATE_REQUESTED + - UPDATED + - STARTED + - FINISHED + token: + description: >- + The validity token (such as booking ID, travel ticket etc.) that MaaS + clients will display to validate the trip when starting the leg. + properties: + validityDuration: + description: >- + The rules that MaaS will interpret to schedule, re-validate or + cancel the booking. + type: object + properties: + from: + description: The starting time from which the ticket is valid + $ref: '#/components/schemas/time' + to: + description: The finishing time the ticket is valid for + $ref: '#/components/schemas/time' + meta: + description: >- + Arbitrary metadata the TSP may pass along the ticket to the client + (e.g. a booking code, base64 encoded binary) + type: object + customer: + type: object + required: + - id + - firstName + - lastName + properties: + id: + description: The identifier MaaS uses to identify the customer + type: string + firstName: + description: First name of the customer (e.g. John) + type: string + lastName: + description: Last name of the customer (e.g. Doe) + type: string + phone: + description: Phone number that the customer may be reached from + type: string + options: + type: object + description: Containing an array of available options matching the query + properties: + leg: + $ref: '#/components/schemas/options_leg' + meta: + $ref: '#/components/schemas/options_meta' + options_leg: + type: object + properties: + startTime: + $ref: '#/components/schemas/time' + endTime: + $ref: '#/components/schemas/time' + from: + $ref: '#/components/schemas/options_coordinates' + to: + $ref: '#/components/schemas/options_coordinates' + options_coordinates: + type: object + properties: + lat: + $ref: '#/components/schemas/lat' + lon: + $ref: '#/components/schemas/lon' + options_meta: + type: object + properties: + name: + type: string + description: + type: string + image: + type: string + format: url + car: + type: object + properties: + passengers: + type: integer + leg: + type: object + description: >- + A OpenTripPlanner compatible definition of a leg (see OpenTripPlanner + docs for reference) + additionalProperties: true + properties: + from: + description: The coordinates the TSP should use to resolve leg start location + $ref: '#/components/schemas/place' + to: + description: The coordinates the TSP should use to resolve leg finish location + $ref: '#/components/schemas/place' + startTime: + $ref: '#/components/schemas/time' + endTime: + $ref: '#/components/schemas/time' + mode: + $ref: '#/components/schemas/mode' + departureDelay: + $ref: '#/components/schemas/duration' + arrivalDelay: + $ref: '#/components/schemas/duration' + distance: + $ref: '#/components/schemas/distance' + fare: + $ref: '#/components/schemas/fare' + route: + type: string + routeShortName: + type: string + routeLongName: + type: string + agencyId: + type: string + legGeometry: + $ref: '#/components/schemas/legGeometry' + required: + - from + - to + - mode + - startTime + - endTime + place: + type: object + additionalProperties: true + properties: + name: + description: Human readable name of the place + type: string + stopId: + type: string + stopCode: + type: string + lat: + $ref: '#/components/schemas/lat' + lon: + $ref: '#/components/schemas/lon' + required: + - lon + - lat + lat: + type: number + minimum: -90 + maximum: 90 + lon: + type: number + minimum: -180 + maximum: 180 + legGeometry: + type: object + additionalProperties: true + properties: + points: + type: string + minLength: 1 + time: + description: >- + A UTC timestamp (number of milliseconds in a Date object since January + 1, 1970, 00:00:00) + duration: + description: A duration of some time (relative to time) in milliseconds + type: integer + maximum: 2147483647 + minimum: 0 + distance: + description: The estimated distance travelled in the leg (in meters) + type: integer + minimum: 0 + fare: + description: Arbitrary fare data that MaaS will use internally + type: object + mode: + description: The type of the leg MaaS uses to identify the leg + links: {} + callbacks: {} From 61185b97e02b8ef3890da23d906f6b90e39ef6e3 Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Wed, 27 Jun 2018 16:02:55 +0300 Subject: [PATCH 02/19] Update version, title, and description --- booking.yaml | 25 ++++++------------------- 1 file changed, 6 insertions(+), 19 deletions(-) diff --git a/booking.yaml b/booking.yaml index 102399e..8026ac3 100644 --- a/booking.yaml +++ b/booking.yaml @@ -1,30 +1,17 @@ openapi: 3.0.0 servers: [] info: - version: v1 - title: MaaS-TSP + version: 0.1 + title: Booking API description: > This is a API specification of REST endpoints that a Transport Service - Provider (TSP) should implement to receive messages from MaaS. It is written - in machine readable [Swagger](http://swagger.io/) format, so thatAPI + Provider (TSP) should implement to receive messages from MaaS Operator(s). It is written + in machine readable [Swagger](http://swagger.io/) format, so that API endpoints, validators and test clients can be generated from the documentation. - - - In addition to this documentation, MaaS maintains a [reference - implementation (**TODO**)](https://github.com/maasglobal/maas-tsp-api) with - test cases. It is also running as a [reference service - (**TODO**)](https://tsp.maas.global/). - - - Right now MaaS TSP API consists of the Booking API. In addition, a need for - customer feedback API (for mediating customer feedback to a TSP) and - administration API (for changing API keys etc.) may be defined. - termsOfService: 'http://api.maas.global/terms/' contact: - name: MaaS API Team - email: developers@maas.fi - url: 'http://maas.fi/' + name: MaaS Alliance + url: 'https://maas-alliance.eu/' license: name: MIT url: 'http://opensource.org/licenses/MIT' From 258666e751bf0c9dc75bdea6ec419ec9cc64cee0 Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 2 Jul 2018 15:43:32 +0300 Subject: [PATCH 03/19] v0.1.0 --- booking.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/booking.yaml b/booking.yaml index 8026ac3..e7877cf 100644 --- a/booking.yaml +++ b/booking.yaml @@ -1,7 +1,7 @@ openapi: 3.0.0 servers: [] info: - version: 0.1 + version: 0.1.0 title: Booking API description: > This is a API specification of REST endpoints that a Transport Service From 30ffcb8d336e723294acd655e4c60c3df79a9405 Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 2 Jul 2018 15:44:28 +0300 Subject: [PATCH 04/19] OpenAPI Specification --- booking.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/booking.yaml b/booking.yaml index e7877cf..2709c1d 100644 --- a/booking.yaml +++ b/booking.yaml @@ -6,7 +6,7 @@ info: description: > This is a API specification of REST endpoints that a Transport Service Provider (TSP) should implement to receive messages from MaaS Operator(s). It is written - in machine readable [Swagger](http://swagger.io/) format, so that API + in machine readable [OpenAPI Specification](https://www.openapis.org/) format, so that API endpoints, validators and test clients can be generated from the documentation. contact: From 35fdf0700e6418692092cc5671028239420c82c2 Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 2 Jul 2018 15:52:39 +0300 Subject: [PATCH 05/19] Add Booking overview MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Tomi Niittumäki Feijk@users.noreply.github.com Co-authored-by: Lauri Svan laurisvan@users.noreply.github.com --- docs/booking.md | 103 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 docs/booking.md diff --git a/docs/booking.md b/docs/booking.md new file mode 100644 index 0000000..a51c594 --- /dev/null +++ b/docs/booking.md @@ -0,0 +1,103 @@ +# MaaS Transport Service Provider Booking API + +The following scenario explains the life-cycle of an individual trip +from a TSP viewpoint. Whenever a new concept (such as an actor or action) +is represented, it is imprinted in **bold**. + +This scenario, with a few extra details is detailed in the process diagram +below. It should be noted from the picture that MaaS more often acts as a +caller than a callee for Transport Service Provider. + +The cases of how MaaS interacts with TSP are depicted below +![Maas-TSP Business Process](https://cdn.rawgit.com/maas-alliance/apis/master/docs/maas-v1-overall.svg) +[source](https://github.com/maas-alliance/apis/blob/master/docs/maas-v1-overall.svg "MaaS-TSP Business Process"). + +## Planning a Route + +**User** **queries** for a **Route** with an address or latitude-logitude +pair from one place to another. MaaS queries the route from a third party +**Routing Engine** that contains the data for **TSP** routes. At this point +MaaS makes no queries to the TSP - it expects the Routing Engine contains +valid GTFS data for the TSP. + +**MaaS** shows several possible **Plans**, each containing a valid +**Route** with several **Legs** with a part of a route using a specific +TSP. + +## Creating a Booking + +User browses through the Plans and chooses to book a trip. For each Leg +in the Plan Route, MaaS creates a new **Booking** for a TSP. +It should be noted that the booking may be hours or days in +advance - a bit like in booking a hotel. The booking contains the +individual Leg as the detailed travel plan for the TSP, as well as +customer contact information. + +TSP receives the booking and confirms the trip. TSP may modify the details +of the Booking, such as moving the **start location** to closest known +street address or delaying the Leg **start time**, as long as the +**end time** can be guaranteed. The Booking is supplemented with +**booked** state information and additional **terms** latest such as +the latest **cancellation time**. + +MaaS checks that the booking succeeded and stores the Booking for future +reference. + +## Navigating a Route + +User starts to navigate the Route. MaaS tracks for the user location to +know if there are any changes needed in the plan. MaaS triggers the changes +for bookings by monitoring the individual Legs. + +MaaS monitors the Booking terms and Leg **start time**. +When the actual Leg starts, MaaS **starts** the Leg and notifies the TSP. +User or TSP may request changes to the Booking, e.g. in a case of a delay +or cancellation. + +Each of these scenarios are described below. + +## Updating a Booking + +A Booking may be updated by a User, MaaS or TSP when any party receives +new information that the Leg needs to be changed. Since the update may need +confirmation from User or a 3rd party system, it is an asynchronous +operation. + +Either party (MaaS or TSP) may send an updated Booking with +**UPDATE_REQUESTED** state. The recipient processes the request +asynchronously and either confirms the request with **UPDATED** state, +sends its proposal with **UPDATE_REQUESTED**, or cancels the leg with +**CANCELLED** state. + +## Cancelling a Booking + +A Booking may be cancelled by User or MaaS within **cancellation time** in +**terms** of the Booking without a specific request. MaaS sends a modified +Booking with state **CANCELLED** information. TSP confirms and updates its +own systems. + +It should be noted that cancellation is an exception case and is likely +happen only when the user chooses to cancel the whole route Plan. +Instead, MaaS and/or TSP should update the booking with new information. + +TSP can assume Booking as paid if the cancellation time has passed and no +cancellation has been received from MaaS. + +## Paying a Booking + +A Booking may be paid (e.g. confirmed) before the **cancellation time** +in **terms** has expired. MaaS sends a modified Booking with **PAID** +state wich the TSP confirms. + +TSP can assume Booking as paid if the cancellation time has passed and no +cancellation has been received from MaaS. + +## Error Cases + +It may be possible that MaaS sends an invalid request or the TSP cannot +fulfill a request. In any such case, TSP may respond with an error. If +TSP responds with an error, MaaS assumes the state was not changed (e.g. +a transaction was rolled back). MaaS may repeat the request +with the same or different data later on. + +The same principle applies when TSP is communicating with MaaS. From 2833e39a57cdba923564acf7b8fa42db543cf932 Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 2 Jul 2018 15:55:33 +0300 Subject: [PATCH 06/19] Create booking-overview.svg Co-authored-by: Lauri Svan laurisvan@users.noreply.github.com --- docs/booking-overview.svg | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 docs/booking-overview.svg diff --git a/docs/booking-overview.svg b/docs/booking-overview.svg new file mode 100644 index 0000000..18d9ad7 --- /dev/null +++ b/docs/booking-overview.svg @@ -0,0 +1,4 @@ + + + +User / AppValidateTicketAbout toComplete LegTrip finishedNotify Leg Completed Give FeedbackLegCompletedAbout to Start a LegPlan a new TripQuery a RouteBook a RouteNavigationStart a LegNewBookingMaaSNotify Leg Completed Store FeedbackScheduledpaymentTicketPaidQuery a Route"Stamp the Ticket" Scheduled Stamping Automatic (re)validation Scheduled Revalidation Pay a BookingUpload Route & Schedule Data Book Route Legs RescheduleLegsTransport Service ProviderValidate a TicketReceiveFeedbackStore Leg Completed NewTransportServiceUpdate Route & Schedule Data Pay a BookingCreate a Booking Change inBookingconditionsUpdate bookingCancel a Booking Update aBookingStamp a Ticket3rd Party SystemsStore the GTFS data Query RouteGTFS DataGTFSDumpGTFSDumpUpdatedBookingValid[true/false]Booking[Paid]BookingBooking[Booked]Booking[Update requested] Booking[Cancelled]Booking[Updated]UpdateBookingUpdatedBookingNewBookingBookingBooking[Paid][manual stamping]Booking [Started]Booking[Started]Booking[Started]Booking[Started]ValidateBooking[Validated] From 805217a65782991e546eb5924df39d12951bd89c Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 2 Jul 2018 15:56:03 +0300 Subject: [PATCH 07/19] Rename booking-overview.svg to booking-process.svg --- docs/{booking-overview.svg => booking-process.svg} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{booking-overview.svg => booking-process.svg} (100%) diff --git a/docs/booking-overview.svg b/docs/booking-process.svg similarity index 100% rename from docs/booking-overview.svg rename to docs/booking-process.svg From 527fd483e860cc3065eb6be4628072463dbe2217 Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 2 Jul 2018 15:56:47 +0300 Subject: [PATCH 08/19] Fix links to booking-process.svg --- docs/booking.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/booking.md b/docs/booking.md index a51c594..8d15a6d 100644 --- a/docs/booking.md +++ b/docs/booking.md @@ -9,8 +9,8 @@ below. It should be noted from the picture that MaaS more often acts as a caller than a callee for Transport Service Provider. The cases of how MaaS interacts with TSP are depicted below -![Maas-TSP Business Process](https://cdn.rawgit.com/maas-alliance/apis/master/docs/maas-v1-overall.svg) -[source](https://github.com/maas-alliance/apis/blob/master/docs/maas-v1-overall.svg "MaaS-TSP Business Process"). +![Maas-TSP Business Process](https://cdn.rawgit.com/maas-alliance/apis/master/docs/booking-process.svg) +[source](https://github.com/maas-alliance/apis/blob/master/docs/booking-process.svg "MaaS-TSP Business Process"). ## Planning a Route From 9e84febb793c607568d6739a3a364e0268bb6554 Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 2 Jul 2018 15:58:19 +0300 Subject: [PATCH 09/19] Update link to booking scenarios --- booking.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/booking.yaml b/booking.yaml index 2709c1d..bd80dfe 100644 --- a/booking.yaml +++ b/booking.yaml @@ -23,7 +23,7 @@ tags: TSP. externalDocs: description: Booking scenarios - url: 'https://github.com/maasglobal/maas-tsp-api/blob/master/specs/Booking.md' + url: 'https://github.com/maas-alliance/apis/blob/booking-api/docs/booking.md' - name: Listing description: >- Before a booking can be made via a TSP, available options at a given From 0c0f6db586d1c2c3a25f08a94202589275eedffd Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 2 Jul 2018 15:59:43 +0300 Subject: [PATCH 10/19] Remove TODO endpoints --- booking.yaml | 9 --------- 1 file changed, 9 deletions(-) diff --git a/booking.yaml b/booking.yaml index bd80dfe..edff25e 100644 --- a/booking.yaml +++ b/booking.yaml @@ -28,15 +28,6 @@ tags: description: >- Before a booking can be made via a TSP, available options at a given location can be listed as follows - - name: TODO Feedback - description: >- - In order to receive customer feedback through MaaS, TSP may implement - these APIs. - - name: TODO Admin - description: >- - In the future MaaS will implement machine-readable APIs that a TSP may use - to update GTFS route information, API keys and other information that is - needed for communicating between MaaS and a TSP. security: - key: [] paths: From 80aa2e1631639abdf5e3a3500fa3435979cf1bc9 Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 2 Jul 2018 16:00:40 +0300 Subject: [PATCH 11/19] Cleanup for validation --- booking.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/booking.yaml b/booking.yaml index edff25e..e85401e 100644 --- a/booking.yaml +++ b/booking.yaml @@ -65,7 +65,6 @@ paths: content: application/json: schema: - name: options type: array description: Available transport options for the queried TSP items: From 416093010d5792362b6d3eac48b14ee779a1b3d1 Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 2 Jul 2018 16:03:00 +0300 Subject: [PATCH 12/19] Add startTime parameter --- booking.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/booking.yaml b/booking.yaml index e85401e..7d147d8 100644 --- a/booking.yaml +++ b/booking.yaml @@ -57,6 +57,11 @@ paths: type: string pattern: >- ^[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)$ + - name: startTime + in: query + schema: + type: string + format: date-time responses: '200': description: >- From 75cbda6b4ecdc73eb78486d2c76f7b8834277d3b Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 2 Jul 2018 16:04:19 +0300 Subject: [PATCH 13/19] Add startTime parameter --- booking.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/booking.yaml b/booking.yaml index 7d147d8..1fe2444 100644 --- a/booking.yaml +++ b/booking.yaml @@ -97,6 +97,11 @@ paths: format: >- enum - BOOKED - CANCELLED - PAID - UPDATE_REQUESTED - UPDATED - STARTED - FINISHED + - name: startTime + in: query + schema: + type: string + format: date-time responses: '200': description: The bookings matching the query From 6fffa60e19064879ea50e29b2e949c3a2b0209e7 Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 2 Jul 2018 16:05:52 +0300 Subject: [PATCH 14/19] Change to enum formatting --- booking.yaml | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/booking.yaml b/booking.yaml index 1fe2444..43221e1 100644 --- a/booking.yaml +++ b/booking.yaml @@ -94,9 +94,14 @@ paths: required: true schema: type: string - format: >- - enum - BOOKED - CANCELLED - PAID - UPDATE_REQUESTED - UPDATED - - STARTED - FINISHED + enum: + - BOOKED + - CANCELLED + - PAID + - UPDATE_REQUESTED + - UPDATED + - STARTED + - FINISHED - name: startTime in: query schema: From eb427421b3c2569d552c92c8774d0869597ec404 Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 6 Aug 2018 12:39:01 +0300 Subject: [PATCH 15/19] ISO 8601 date/time --- booking.yaml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/booking.yaml b/booking.yaml index 43221e1..b816374 100644 --- a/booking.yaml +++ b/booking.yaml @@ -501,8 +501,7 @@ components: minLength: 1 time: description: >- - A UTC timestamp (number of milliseconds in a Date object since January - 1, 1970, 00:00:00) + An ISO 8601 date/time expression (e.g. YYYY-mm-ddThh:mm:ss) duration: description: A duration of some time (relative to time) in milliseconds type: integer From f957154300d0beb08da56eb72393bd3ae78eed2d Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 6 Aug 2018 14:42:16 +0300 Subject: [PATCH 16/19] Remove x-serverless-endpoint --- booking.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/booking.yaml b/booking.yaml index b816374..cc8b2ed 100644 --- a/booking.yaml +++ b/booking.yaml @@ -136,7 +136,6 @@ paths: application/json: schema: $ref: '#/components/schemas/error' - x-serverless-endpoint: echo~GET post: description: >- Creates a new `Booking` for the TSP in **booked** state. The returned From 7dd172fb7d23a7b732d43fd728c33b91d4fdb1dd Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 6 Aug 2018 14:44:47 +0300 Subject: [PATCH 17/19] Clarify state and terms --- booking.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/booking.yaml b/booking.yaml index cc8b2ed..6ab1d3d 100644 --- a/booking.yaml +++ b/booking.yaml @@ -314,9 +314,11 @@ components: description: The identifier MaaS will be using to referring to the booking type: string state: - $ref: '#/components/schemas/bookingState' + description: The state of the booking (e.g. 'complete', 'cancelled') + type: string terms: - $ref: '#/components/schemas/bookingState' + description: Any additional terms related to the booking (e.g. terms of service) + type: string token: $ref: '#/components/schemas/token' meta: From 45ba8bbf0943059ad7f6a0966e3d519b00634262 Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 6 Aug 2018 14:46:44 +0300 Subject: [PATCH 18/19] Revert change to booking state reference --- booking.yaml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/booking.yaml b/booking.yaml index 6ab1d3d..8cb990a 100644 --- a/booking.yaml +++ b/booking.yaml @@ -314,8 +314,7 @@ components: description: The identifier MaaS will be using to referring to the booking type: string state: - description: The state of the booking (e.g. 'complete', 'cancelled') - type: string + $ref: '#/components/schemas/bookingState' terms: description: Any additional terms related to the booking (e.g. terms of service) type: string From af02e36998ddcca9db1d9b9b29ad7ec18da6e16c Mon Sep 17 00:00:00 2001 From: Brylie Christopher Oxley Date: Mon, 6 Aug 2018 17:10:28 +0300 Subject: [PATCH 19/19] Fix options data type --- booking.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/booking.yaml b/booking.yaml index 8cb990a..2712666 100644 --- a/booking.yaml +++ b/booking.yaml @@ -383,7 +383,7 @@ components: description: Phone number that the customer may be reached from type: string options: - type: object + type: array description: Containing an array of available options matching the query properties: leg: