swagger.yml

---
openapi: 3.1.0
info:
  title: Reservations/Bookings
  description: API to work with X in the area
  version: 1.0.0
servers:
- url: https://api.parkmobile.io/availability/v1
  description: Production (Internal)
paths:
  "/":
    x-public: true
    get:
      summary: This is the root path
      operationId: getNothing
      tags:
      - root
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Response"
        '400':
          description: The Input from the user was malformed
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                error: Bad Request Error
                error_code: AV-1001
        '401':
          description: Authorization value is missing for the header or the credentials
            provided are incorrect
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                status_code: 401
                error_message: Authorization Error
        '403':
          description: The account specified does not have the required role(s) to
            access the resource
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                status_code: 403
                error_message: Invalid Access Rights Error
        '404':
          description: Attempting to access invalid routes
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                status_code: 404
                error_message: Page Not Found
        '500':
          description: An error occurred on the server. The response body includes
            details of the specific error
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                error: Internal Server Error
                error_code: AV-1010
  "/availability":
    x-public: true
    get:
      summary: This is the call to find if there are spaces available
      operationId: getAvailability
      tags:
      - Availability
      parameters:
      - in: query
        name: location_id
        required: true
        schema:
          type: string
      - in: query
        name: start_time
        required: true
        schema:
          type: string
      - in: query
        name: stop_time
        required: true
        schema:
          type: string      
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Response"
        '400':
          description: The Input from the user was malformed
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                error: Bad Request Error
                error_code: AV-1001
        '401':
          description: Authorization value is missing for the header or the credentials
            provided are incorrect
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                status_code: 401
                error_message: Authorization Error
        '403':
          description: The account specified does not have the required role(s) to
            access the resource
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                status_code: 403
                error_message: Invalid Access Rights Error
        '404':
          description: Attempting to access invalid routes
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                status_code: 404
                error_message: Page Not Found
        '500':
          description: An error occurred on the server. The response body includes
            details of the specific error
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                error: Internal Server Error
                error_code: AV-1010
  "/locations":
    x-public: true
    get:
      tags:
      - Locations
      summary: Get the locations that are available to paint the map for a given timestamp
      operationId: getLocations
      parameters:
      - in: query
        name: country_code
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Alive
        '401':
          description: Authorization value is missing for the header or the credentials
            provided are incorrect
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                status_code: 401
                error_message: Authorization Error
        '403':
          description: The account specified does not have the required role(s) to
            access the resource
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                status_code: 403
                error_message: Invalid Access Rights Error
        '404':
          description: Attempting to access invalid routes
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                status_code: 404
                error_message: Page Not Found
  "/rates":
    x-public: true
    get:
      tags:
      - Rates
      summary: Find the rates for the selected location
      operationId: getRates
      parameters:
      - in: query
        name: id
        required: true
        schema:
          type: string
      - in: query
        name: location_id
        required: true
        schema:
          type: string
      - in: query
        name: price
        required: true
        schema:
          type: string
      - in: query
        name: currency
        required: true
        schema:
          type: string
      - in: query
        name: vehicle_types
        required: true
        schema:
          type: string
      - in: query
        name: access_type
        required: true
        schema:
          type: string
        example: "onepass"
        description: The permission to enter or not more than once per session
      - in: query
        name: description
        required: true
        schema:
          type: string
        example: "This is the possible wording for the rate provided by the operator"
        description: Parameter to hold additional text that the provider may want to add to their rate
      responses:
        '200':
          description: Alive
        '401':
          description: Authorization value is missing for the header or the credentials
            provided are incorrect
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                status_code: 401
                error_message: Authorization Error
        '403':
          description: The account specified does not have the required role(s) to
            access the resource
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                status_code: 403
                error_message: Invalid Access Rights Error
        '404':
          description: Attempting to access invalid routes
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                status_code: 404
                error_message: Page Not Found
  "/booking":
    x-public: false
    post:
      tags:
      - Booking
      summary: API to place a parking order and confirm a booking
      operationId: postBooking
      parameters:
      - in: query
        name: location_id
        required: true
        schema:
          type: string
      - in: query
        name: start_time
        required: true
        schema:
          type: string
      - in: query
        name: stop_time
        required: true
        schema:
          type: string 
      - in: query
        name: rate_id
        required: true
        schema:
          type: string
      - in: query
        name: customer_id
        required: true
        schema:
          type: string 
      responses:
        '200':
          description: Alive
        '401':
          description: Authorization value is missing for the header or the credentials
            provided are incorrect
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                status_code: 401
                error_message: Authorization Error
        '403':
          description: The account specified does not have the required role(s) to
            access the resource
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                status_code: 403
                error_message: Invalid Access Rights Error
        '404':
          description: Attempting to access invalid routes
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                status_code: 404
                error_message: Page Not Found
  "/charge":
    x-public: false
    post:
      tags:
      - Charge
      summary: Send internal call to make the payments
      operationId: postCharge
      parameters:
      - in: query
        name: booking_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Alive
        '401':
          description: Authorization value is missing for the header or the credentials
            provided are incorrect
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                status_code: 401
                error_message: Authorization Error
        '403':
          description: The account specified does not have the required role(s) to
            access the resource
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                status_code: 403
                error_message: Invalid Access Rights Error
        '404':
          description: Attempting to access invalid routes
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Error"
              example:
                status_code: 404
                error_message: Page Not Found
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: error message
          example: Error Getting Information
        error_code:
          type: string
          description: An error code to give Easypark Information specific error
            details
          enum:
          - 'AV-1001: NotAvailable'
          - 'AV-1002: PaymentNotAllowed'
          example: AV-1001
      title: Error Schema
    Response:
      type: object
      properties:
        id:
          type: string
          example: pk-139
          description: Internal unique identifier (can be used as location_id)
        name:
          type: string
          example: State Farm Arena
          description: Name of the location
        address:
          type: string
          example: "Carrer Anselm Clavé, 25, Blanes"
          description: Address of the location
        latitude:
          type: string
          example: 41.676337
          description: Latitude of the location
        longitude:
          type: string
          example: 2.789064
          description: Longitude of the location
        cover_image:
          type: string
          example: "https://media.parkimeter.com/images/parkings/medium/139-77315a2b13bd3221d3775434acf41079.jpg"
          description: Image that can be use in the cover of the site
        available:
          type: boolean
          example: false
          description: There is availabilty to process a booking
        count:
          type: number
          example: 100
          description: The amount of spaces that are available
        vehicle_types:
          type: array
          items:
            type: object
            properties:
              name:
                type: object
                properties:
                  name:
                    type: string
                    enum: 
                    - car
                    - motorcyle
                    - Standard Auto
                    - Oversized Vehicle
                    description: Vechile types that are allowed to park in the selected location
                description: Array of vehicle types
            description: Array of vehicle types
        rate_id:
          type: string
          example: pk-7272
          description: Rate unique identifier
        customer_id:
          type: string
          example: "1"
          description: Customer unique identifier
        start_time:
          type: string
          example: "2022-06-21T09:00:00Z"
          description: Booking start time, in ISO 8601 format
        stop_time:
          type: string
          example: "2022-06-21T11:00:00Z"
          description: Booking stop time, in ISO 8601 format
        status:
          type: string
          description: Booking status
          enum:
          - pending
          - paid
          example: pending
        error:
          type: string
          description: An error code to give Easypark Availability specific error
            details
          enum:
          - 'AV-1001: RequestBodyError'
          - 'AV-1002: InvalidAction'
          - 'AV-1003: ItemError'
          - 'AV-1005: UserFailure'
          - 'AV-1006: ProviderFailure'
          - 'AV-1007: SpaceDataRequestFailure'
          - 'AV-1010: FatalError'
          example: AV-1001
      title: Availability Response Schema
  responses:
    BadRequest:
      description: 400 - The Input from the user was malformed
      content:
        "*/*":
          schema:
            "$ref": "#/components/schemas/Error"
    InternalServerError:
      description: 500 - An error occurred on the server. The response body includes
        details of the specific error
      content:
        "*/*":
          schema:
            "$ref": "#/components/schemas/Error"
    NotFound:
      description: 404 - Attempting to access invalid routes
      content:
        "*/*":
          schema:
            "$ref": "#/components/schemas/Error"
    Unauthorized:
      description: 401 - Authorization value is missing for the header or the credentials
        provided are incorrect
      content:
        "*/*":
          schema:
            "$ref": "#/components/schemas/Error"
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header