diff --git a/specs/maas-v1.yml b/specs/maas-v1.yml index 461656f..102399e 100644 --- a/specs/maas-v1.yml +++ b/specs/maas-v1.yml @@ -1,537 +1,529 @@ -swagger: '2.0' - -# This is your document metadata +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. + 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/). - termsOfService: http://api.maas.global/terms/ + + 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/ + url: 'http://maas.fi/' license: name: MIT - url: http://opensource.org/licenses/MIT -schemes: - - https - + 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 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 + 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 + 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. - + 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. - -securityDefinitions: - 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 + 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. + 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 - schemes: - - https - consumes: - - query - produces: - - application/json parameters: - name: from - description: User's location in comma separated form e.g. 60.123,27.456 + description: 'User''s location in comma separated form e.g. 60.123,27.456' in: query required: true - type: string - pattern: ^[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)$ + 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 + description: 'A desired destination e.g. 60.123,27.456' in: query required: false - type: string - pattern: ^[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)$ - - name: startTime - description: Check availability of transportation in future. Must be noted that not all providers (TSP's) support reservation or availability listing in future, thus optional. - in: query - required: false - $ref: '#/definitions/time' - - name: endTime - description: A possible end time e.g. for a car rental - required: false - $ref: '#/definitions/time' - - name: mode - required: false - $ref: '#/definitions/mode' - - responses: - 200: - description: Available transport methods matching the given query parameters. If no transport methods are available, an empty array is returned. - schema: - name: options - type: array - description: Available transport options for the queried TSP - items: - $ref: '#/definitions/options' - 400: - description: If coordinates given in the request are invalid the server returns 400 Bad request as a response. schema: - $ref: '#/definitions/error' - + 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 + description: Returns the `Booking` that has been created earlier tags: - Booking - schemes: - - https - consumes: - - application/json - produces: - - application/json parameters: - name: state description: The state the booking to fetch in: query required: true - type: string - format: enum - - BOOKED - - CANCELLED - - PAID - - UPDATE_REQUESTED - - UPDATED - - STARTED - - FINISHED - + schema: + type: string + format: >- + enum - BOOKED - CANCELLED - PAID - UPDATE_REQUESTED - UPDATED - + STARTED - FINISHED responses: - 200: + '200': description: The bookings matching the query - schema: - type: array - description: The bookings that matched the query (zero or more) - minItems: 0 - items: - $ref: '#/definitions/booking' - 400: + 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) - schema: - $ref: '#/definitions/error' - 401: + content: + application/json: + schema: + $ref: '#/components/schemas/error' + '401': description: Authorization error (invalid API key) - schema: - $ref: '#/definitions/error' + content: + application/json: + schema: + $ref: '#/components/schemas/error' default: description: unexpected error - schema: - $ref: '#/definitions/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. + 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. + 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. + 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 - schemes: - - https - consumes: - - application/json - produces: - - application/json - parameters: - - name: newBooking - in: body - description: New `Booking` data - required: true - schema: - $ref: '#/definitions/newBooking' responses: - 200: + '200': description: A new booking was succesfully created - schema: - $ref: '#/definitions/booking' - 400: + content: + application/json: + schema: + $ref: '#/components/schemas/booking' + '400': description: Bad request (invalid body parameters) - schema: - $ref: '#/definitions/error' - 401: + content: + application/json: + schema: + $ref: '#/components/schemas/error' + '401': description: Authorization error (invalid API key) - schema: - $ref: '#/definitions/error' - + content: + application/json: + schema: + $ref: '#/components/schemas/error' default: description: Unexpected error - schema: - $ref: '#/definitions/error' - - /bookings/{id}: + 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. + description: Returns the `Bookings` that have been created through the system. tags: - Booking - schemes: - - https - consumes: - - application/json - produces: - - application/json parameters: - name: id in: path description: Booking identifier required: true - type: string + schema: + type: string responses: - 200: + '200': description: The booking was found - schema: - $ref: '#/definitions/booking' - 400: + content: + application/json: + schema: + $ref: '#/components/schemas/booking' + '400': description: Bad request (invalid query or body parameters) - schema: - $ref: '#/definitions/error' - 401: + content: + application/json: + schema: + $ref: '#/components/schemas/error' + '401': description: Authorization error (invalid API key) - schema: - $ref: '#/definitions/error' - 404: + content: + application/json: + schema: + $ref: '#/components/schemas/error' + '404': description: The booking was not found - schema: - $ref: '#/definitions/error' + content: + application/json: + schema: + $ref: '#/components/schemas/error' default: description: Unexpected error - schema: - $ref: '#/definitions/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. + 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 - schemes: - - https - consumes: - - application/json - produces: - - application/json parameters: - name: id in: path description: Booking identifier required: true - type: string - - name: booking - in: body - description: New `Booking` data - required: true schema: - $ref: '#/definitions/booking' + type: string responses: - 200: + '200': description: The booking was modified - schema: - $ref: '#/definitions/booking' + content: + application/json: + schema: + $ref: '#/components/schemas/booking' default: description: Unexpected error - schema: - $ref: '#/definitions/error' - -definitions: - 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: '#/definitions/leg' - customer: - $ref: '#/definitions/customer' - - booking: - type: object - description: The booking information describing the state and details of the transaction - allOf: - - $ref: '#/definitions/newBooking' - properties: - id: - description: The identifier MaaS will be using to referring to the booking - type: string - state: - $ref: '#/definitions/bookingState' - terms: - $ref: '#/definitions/bookingState' - token: - $ref: '#/definitions/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: '#/definitions/time' - to: - description: The finishing time the ticket is valid for - $ref: '#/definitions/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 - #pattern: "^(\\\\+\\\\d{1,3}\\\\s|0)?(\\\\d{2})?(\\\\d{3,8}$" - - options: - type: object - description: Containing an array of available options matching the query - properties: - leg: - $ref: '#/definitions/options_leg' - meta: - $ref: '#/definitions/options_meta' - - options_leg: - type: object - properties: - startTime: - $ref: "#/definitions/time" - endTime: - $ref: "#/definitions/time" - from: - $ref: "#/definitions/options_coordinates" - to: - $ref: "#/definitions/options_coordinates" - - options_coordinates: - type: object - properties: - lat: - $ref: "#/definitions/lat" - lon: - $ref: "#/definitions/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: "#/definitions/place" - to: - description: The coordinates the TSP should use to resolve leg finish location - $ref: "#/definitions/place" - startTime: - $ref: "#/definitions/time" - endTime: - $ref: "#/definitions/time" - mode: - $ref: "#/definitions/mode" - departureDelay: - $ref: "#/definitions/duration" - arrivalDelay: - $ref: "#/definitions/duration" - distance: - $ref: "#/definitions/distance" - fare: - $ref: "#/definitions/fare" - route: - type: string - routeShortName: - type: string - routeLongName: - type: string - agencyId: - type: string - legGeometry: - $ref: "#/definitions/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: "#/definitions/lat" - lon: - $ref: "#/definitions/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) - type: integer - maximum: 2147483647 - minimum: 0 - - 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 - type: string - enum: - - WALK - - BICYCLE - - CAR - - TRAM - - SUBWAY - - RAIL - - BUS - - FERRY - - CABLE_CAR - - GONDOLA - - FUNICULAR - - TRANSIT - - TRAINISH - - BUSISH - - LEG_SWITCH - - TAXI + 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: {}