standard_covoit.yaml

openapi: 3.0.1
info:
  title: ""
  description: ""
  version: 0.0.1
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
tags:
  - name: Search
    description: API routes to search for journeys. These routes can be left opened to public.

#
# API Routes    
#
paths:
  /driver_journeys:
    get:
      tags:
      - Search
      summary: Search for matching punctual planned outward driver journeys.
      description: Route used to retrieve a collection of punctual planned outward driver journeys matching the provided criteria.
      operationId: getDriverJourneys
      parameters:
        - $ref: '#/components/parameters/departureLat'
        - $ref: '#/components/parameters/departureLng'
        - $ref: '#/components/parameters/arrivalLat'
        - $ref: '#/components/parameters/arrivalLng'
        - $ref: '#/components/parameters/departureDate'
        - $ref: '#/components/parameters/timeDelta'
        - $ref: '#/components/parameters/departureRadius'
        - $ref: '#/components/parameters/arrivalRadius'
        - $ref: '#/components/parameters/count'
      responses:
        200:
          description: Ok. Request processed successfully.
          content:
            application/json:
              schema:
                title: DriverJourneys
                type: array
                items:
                  $ref: '#/components/schemas/DriverJourney'
        400:
          description: Bad Request. See error message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: |-
                      Explain why the request couldn't be processed.
        401:
          description: Unauthorized. You must authenticate.
        429:
          description: Too Many Requests. Please slow down.
          headers:
            Retry-After:
              description: |-
                How long to wait before making a new request (in seconds).
              schema:
                type: integer
        500:
          description: Internal Server Error. Please try again later.


  /passenger_journeys:
    get:
      tags:
      - Search
      summary: Search for matching punctual planned outward passenger journeys.
      description: Route used to retrieve a collection of punctual planned outward passenger journeys matching the provided criteria.
      operationId: getPassengerJourneys
      parameters:
        - $ref: '#/components/parameters/departureLat'
        - $ref: '#/components/parameters/departureLng'
        - $ref: '#/components/parameters/arrivalLat'
        - $ref: '#/components/parameters/arrivalLng'
        - $ref: '#/components/parameters/departureDate'
        - $ref: '#/components/parameters/timeDelta'
        - $ref: '#/components/parameters/departureRadius'
        - $ref: '#/components/parameters/arrivalRadius'
        - $ref: '#/components/parameters/count'
      responses:
        200:
          description: Ok. Request processed successfully.
          content:
            application/json:
              schema:
                title: PassengerJourneys
                type: array
                items:
                  $ref: '#/components/schemas/PassengerJourney'
        400:
          description: Bad Request. See error message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: |-
                      Explain why the request couldn't be processed.
        401:
          description: Unauthorized. You must authenticate.
        429:
          description: Too Many Requests. Please slow down.
          headers:
            Retry-After:
              description: |-
                How long to wait before making a new request (in seconds).
              schema:
                type: integer
        500:
          description: Internal Server Error. Please try again later.
          
  /booking:
    post:
      tags:
      - Interact
      summary: Send a booking request to the owner of a journey.
      description: Route used to allow a user to book a carpool to the owner of a journey. While posting a new Booking, its status shall always be set first as `status=pending`. 
        _Reminder:_ The sender must also store the Booking object, and be ready to receive modifications of it through the PATCH /bookings 
      operationId: postBookings
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Booking'
                  
      responses:
        200:
          description: Ok. Request processed successfully.
          content:
            application/json:
              schema:
                title: PassengerJourneys
                type: array
                items:
                  $ref: '#/components/schemas/Booking'
        400:
          description: Bad Request. See error message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: |-
                      Explain why the request couldn't be processed.
        401:
          description: Unauthorized. You must authenticate.
        429:
          description: Too Many Requests. Please slow down.
          headers:
            Retry-After:
              description: |-
                How long to wait before making a new request (in seconds).
              schema:
                type: integer
        500:
          description: Internal Server Error. Please try again later.
          
  /bookings/{bookingId}:
    patch:
      tags:
      - Interact
      summary: Updates status of an existing Booking object.
      description: Route used to update the status of an existing Booking object. Should be used usually just to accept or reject 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'
      responses: 
        200:
          description: Successful operation.
        401:
          description: Unauthorized. Error code can be among  `access_denied, missing_booking_ownerhsip` .
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: |-
                      Explain why the request couldn't be processed.
        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 object.
      description: Route used to retrieve the details of an existing Booking object. Can only be used by the opeartor having created the Booking object. 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/Booking'
        401:
          description: Unauthorized. Error code can be among  `access_denied, missing_booking_ownerhsip` .
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: |-
                      Explain why the request couldn't be processed.
        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:
      - status
      summary: Give health status of the webservice.
      responses:
        200:
          description: Ok. Webservice is available.
        429:
          description: Too Many Requests. Please slow down.
          headers:
            Retry-After:
              description: |-
                How long to wait before making a new request (in seconds).
              schema:
                type: integer
        500:
          description: Internal Server Error. Please try again later.

#
# Schemas 
#              
components:

  parameters:
  
    departureLat:
      name: departureLat
      in: query
      required: true
      schema:
        type: number
      description: Latitude of searched departure point.
      
      
    departureLng:  
      name: departureLng
      in: query
      description: Longitude of searched departure point.
      required: true
      schema:
        type: number
    
    arrivalLat:
      name: arrivalLat
      in: query
      description: Latitude of searched arrival point.
      required: true
      schema:
        type: number
    
    arrivalLng:    
      name: arrivalLng
      in: query
      description: Longitude of searched arrival point.
      required: true
      schema:
        type: number
        
    departureDate:
      name: departureDate
      in: query
      description: Departure datetime using a UNIX UTC timestamp in seconds. 
      schema:
        type: integer
            
    timeDelta:
      name: timeDelta
      in: query
      description: Time margin in seconds. The retrieved journeys must match the
        given time parameters within a +`timeDelta` / -`timeDelta` interval .
      schema:
        type: integer
        default: 900
        
    departureRadius:
      name: departureRadius
      in: query
      description: Search radius in kilometers around the departure point.
      schema:
        type: number
        default: 1.0
        
    arrivalRadius:
      name: arrivalRadius
      in: query
      description: Search radius in kilometers around the arrival point.
      schema:
        type: number
        default: 1.0
        
    count:
      name: count
      in: query
      description: Maximum number of returned journeys. If missing, all matching
        journeys are returned.
      schema:
        type: integer
        
  schemas:
    Journey:
      title: Journey
      required:
      - id
      - duration
      - passengerPickupDate
      - passengerPickupLat
      - passengerPickupLng
      - passengerDropLat
      - passengerDropLng
      - type
      - webUrl
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 255
          description: Journey's id.
            In order to be a basis for carpool proof, this id must match the `journey_id` that could be provided to a carpool proof register as described for example in [this documentation of an open source product for France](https://tech.covoiturage.beta.gouv.fr/partners/preuves/schema.html#schema-json-complet).
    
        passengerPickupDate:
          type: number
          description: |-
            Passenger pickup datetime as a UNIX UTC timestamp in seconds.
          format: long
        passengerPickupLat:
          type: "number"
          format: "double"
          description: Latitude of the passenger pick-up point.
        passengerPickupLng:
          type: "number"
          format: "double"
          description: Longitude of the passenger pick-up point.
        passengerDropLat:
          type: "number"
          format: "double"
          description: Latitude of the passenger drop-off point.
        passengerDropLng:
          type: "number"
          format: "double"
          description: Longitude of the passenger drop-off point.
        passengerPickupAddress:
          type: string
          description: String representing the pickup-up address.
        passengerDropAddress:
          type: string
          description: String representing the drop-off address.
        duration:
          type: integer
          description: Carpooling duration in seconds.
        webUrl:
          type: string
          description: URL of the journey on the webservice provider platform.
        type:
          type: string
          description: |-
            Type of journey. A dynamic journey is happening in real time.
          enum:
          - PLANNED
          - DYNAMIC
          - LINE
        distance:
          type: "integer"
          description: Carpooling distance in meters.
        driverDepartureDate:
          type: number
          description: |-
            Driver departure datetime as a UNIX UTC timestamp in seconds.
          format: long
        driverDepartureLat:
          type: "number"
          format: "double"
          description: Latitude of the departure.
        driverDepartureLng:
          type: "number"
          format: "double"
          description: Longitude of the departure.
        driverArrivalLat:
          type: "number"
          format: "double"
          description: Latitude of the arrival.
        driverArrivalLng:
          type: "number"
          format: "double"
          description: Longitude of the arrival.
        driverDepartureAddress:
          type: string
          description: String representing the departure address of the driver.
        driverArrivalAddress:
          type: string
          description: String representing the arrival address of the driver.
        journeyPolyline:
          type: string
          description: |-
            Carpooling journey itinerary as a
            [Google Encoded Polyline](https://developers.google.com/maps/documentation/utilities/polylinealgorithm).
        price:
          $ref: '#/components/schemas/Price'
        preferences:
          $ref: '#/components/schemas/Preferences'
        deepLink:
          $ref: '#/components/schemas/DeepLink'
          
    DriverJourney:
      allOf:
        - $ref: '#/components/schemas/Journey'
        - type: object
          required:
            - driver
          properties:
            driver:
              $ref: '#/components/schemas/User'
            availableSeats:
              type: integer
              description: If a driver journey, available seats.
            car:
              $ref: '#/components/schemas/Car'
            departureToPickupWalkingTime:
              type: integer
              description: |-
                Walking time from the requested departure location
                to the pick-up location.
            dropoffToArrivalWalkingTime:
              type: integer
              description: |-
                Walking time to the requested arrival location
                from the drop-off location.
            departureToPickupWalkingDistance:
              type: integer
              description: |-
                Walking distance from the requested departure location
                to the pick-up location.
            dropoffToArrivalWalkingDistance:
              type: integer
              description: |-
                Walking distance to the requested arrival location
                from the drop-off location.
            departureToPickupWalkingPolyline:
              type: string
              description: |-
                Walking
                [Google Encoded Polyline](https://developers.google.com/maps/documentation/utilities/polylinealgorithm)
                from the requested departure location to the pick-up location.
            dropoffToArrivalWalkingPolyline:
              type: string
              description: |-
                Walking
                [Google Encoded Polyline](https://developers.google.com/maps/documentation/utilities/polylinealgorithm)
                to the requested arrival location from the drop-off location.
  
            
    PassengerJourney:
      allOf:
        - $ref: '#/components/schemas/Journey'
        - type: object
          required:
            - passenger
          properties:
            passenger:
              $ref: '#/components/schemas/User'
            requestedSeats:
              type: integer
              description: If a passenger journey, requested seats.
          
    Price:
      type: object
      properties:
        type:
          type: string
          description: |-
            Either « FREE », « PAYING » or « UNKNOWN ». « UNKNOWN » is given
            when it should be « PAYING » but we cannot set the price yet.
          enum:
          - FREE
          - PAYING
          - UNKNOWN
        amount:
          type: number
          description: Carpooling passenger cost in euros.
          format: float
        currency:
          type: string
          description: ISO 4217 code representing the currency of the price.

    User:
      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.
        lastName:
          type: string
          description: User's last name.
        grade:
          type: integer
          minimum: 1
          maximum: 5
          description: User's grade from 1 to 5.
        picture:
          type: string
          description: User's profile picture absolute URL.
        gender:
          type: string
          description: User's gender. 'O' stands for 'Other'.
          enum:
            - F
            - M
            - O
        verifiedIdentity:
          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.

    Preferences:
      type: object
      properties:
        smoking:
          type: boolean
          description: |-
            If driver journey, specifies if the driver allows smoking in the car.
        animals:
          type: boolean
          description: |-
            If driver journey, specifies if the driver allows animals in the car.
        music:
          type: boolean
          description: |-
            If driver journey, specifies if the driver enjoys music in the car.
        isTalker:
          type: boolean
          description: |-
            If driver journey, specifies if the driver enjoys talking with passengers.
        luggageSize:
          type: integer
          minimum: 1
          maximum: 5
          description: |-
            If driver journey, specifies the size of allowed luggages.
            From very small (1) to very big (5).

    Car:
      type: object
      properties:
        model:
          type: string
          description: Model of the car.
        brand:
          type: string
          description: Brand of the car.

    DeepLink:
      type: object
      description: Platform specific deep-link configurations.
      properties:
        android:
          type: object
          properties:
            uri:
              type: string
              description: |-
                URI compliant with Android conventions to open the webservice
                provider mobile app on the screen presenting the specific journey
                (see [this guide](https://blog.branch.io/technical-guide-to-deep-linking-on-android-chrome-intents/) for more details).
            storeUrl:
              type: string
              description: |-
                URL of the webservice provider mobile app on the PlayStore
                in case the app is not yet installed on the device.
        ios:
          type: object
          properties:
            universalLink:
              type: string
              description: |-
                URI compliant with iOS conventions to open the webservice
                provider mobile app on the screen presenting the specific journey.
                
    ConnectionMessage:
      type: object
      required:
        - driverJourneyId
        - driverUserid
        - passengerJourneyId
        - passengerUserid
      properties:
        driverJourneyId:
          $ref: '#/components/schemas/journeyId'
        driverUserid:
          type: string
          description: User's id as retrieved by the route GET /driver_journeys.
        driverAlias:
          type: string
          description: Driver's name alias.
        details:
          type: string
          maxLength: 500
          description: Free text content of the 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.
        passengerJourneyId:
          $ref: '#/components/schemas/journeyId'
        passengerUserid:
          type: string
          description: User's id as retrieved by the route GET /passenger_journeys.
        passengerAlias:
          type: string
          description: Passenger's name alias.
        driverOperator:
          $ref: '#/components/schemas/operator'
        driverOperatorWebUrl:
          $ref: '#/components/schemas/operatorUrl'
        passengerOperator:
          $ref: '#/components/schemas/operator'
        passengerOperatorWebUrl:
          $ref: '#/components/schemas/operatorUrl'
          
    Booking:
      allOf:
        - $ref: '#/components/schemas/ConnectionMessage'
      type: object
      required:
        - id
        - frequency
        - outwardSchedule
        - price
      properties:
        id:
          $ref: '#/components/schemas/bookingId'
        passengerPickupDate:
          type: number
          description: |-
            Passenger pickup datetime as a UNIX UTC timestamp in seconds.
          format: long
        status:
          $ref: '#/components/schemas/bookingStatus'
        price:
          type: number
          description: Proposed and agreed (when `status=accepted`) price for the journey.
          
    journeyId:
      type: string
      minLength: 1
      maxLength: 255
      description: Journey's id.
        In order to be a basis for carpool proof, this id must match the `journey_id` that could be provided to a carpool proof register as described for example in [this documentation of an open source product for France](https://tech.covoiturage.beta.gouv.fr/partners/preuves/schema.html#schema-json-complet).
          
          
    bookingId:
      type: string
      description: Booking id is common between both operators, and must be set as a MD5 hashing of a string concatenating the `driverJourneyId`, the `passengerJourneyId` and a UNIX UTC timestamp in seconds.
          
    bookingStatus:
      type: string
      description: Status of the booking.
      enum:
        - pending
        - accepted
        - rejected
        - cancelled
      default: pending
      
    operator:
      type: string
      description: Name of the operator owning this journey.
      
    operatorUrl:
      type: string
      description: Url on the website of the operator owning this journey.