swagger.yaml

openapi: 3.0.3
info:
  title: Family Car Tracker - OpenAPI 3.0
  description: |-
    This is a sample family car tracking application allowing us to book car usage times.
    
    Since I'm are using cookie auth on this Family Car project, the Try It Out feature won't work in browsers due to security limitations. Please use Postman to try these requests.
    
    Database is located in AWS DynamoDB, it's named `development-family-car-booking-app`
  contact:
    email: kushliansky@gmail.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
  - url: https://qa-car-tracker.ilya.online
paths:
  /signup:
    post:
      summary: Sign up with your credentials.
      description: Sign up with your credentials and basic user data.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  example: masha@gmail.com
                  description: Should be the user's email
                password:
                  type: string
                  example: myPassW0rd
                providedCarIds:
                  type: array
                  example: ['ho-123456']
                  default: []
                  description: By default the user does not provide any cars
                availableCarIds:
                  type: array
                  example: ['ho-123456']
                  default: ['ho-123456']
                  description: By default the user gets assigned the Family Honda car. This is done for simplicity. In a real app, the user needs to provide their own car out of a list or create a car on the fly. This app is for educational purposes, so we are removing this complexity.
                firstName:
                  type: string
                  example: Maria
                  description: Your user's name as it will be shown in the application
      responses:
        '200':
          description: Successful signup
          content:
            application/json:
              schema:
                type: object
                properties:
                  IdToken:
                    type: string
                    example: abc
                  AccessToken:
                    type: string
                    example: abc
                  RefreshToken:
                    type: string
                    example: abc

        '400':
          description: Bad request. You did not provide the necessary information for a successful signup.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Bad Request'

  /token/refresh:
    post:
      summary: Refresh access and id token by presenting a secure refresh token
      parameters:
        - in: header
          name: x-refresh-token
          schema:
            type: string
          required: true

      responses:
        '200':
          description: Successful refresh. You will get IdToken and AccessToken back
          content:
            application/json:
              schema:
                type: object
                properties:
                  IdToken:
                    type: string
                    example: abc
                  AccessToken:
                    type: string
                    example: abc

        '401':
          description: Unauthorized. Invalid credentials presented or the refresh token has already been revoked.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Invalid credentials provided'

  /login:
    post:
      summary: Login with your credentials
      description: Supply login and password to authenticate.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  example: masha@mail.com
                password:
                  type: string
                  example: myPassW0rd
      responses:
        '200':
          description: Successful login. You will get IdToken, AccessToken and RefreshToken in the response body
          content:
            application/json:
              schema:
                type: object
                properties:
                  RefreshToken:
                    type: string
                    example: abc
                  IdToken:
                    type: string
                    example: abc
                  AccessToken:
                    type: string
                    example: abc
        '400':
          description: Bad request. You did not provide any credentials at all, so request is incorrect.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'No credentials provided'
        '401':
          description: Unauthorized. Invalid credentials presented.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Invalid credentials provided'

  /me:
    get:
      summary: Get my username
      description: Current user's username by cookie
      parameters:
        - in: header
          name: Authorization
          description: "Access token. The format should be `Authorization: Bearer <your-token>`"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  username:
                    type: string
                    example: mariakazakova92@gmail.com

        '401':
          description: Unauthorized. Invalid cookie presented or cookie was not included in the request or cookie is incorrect.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Unauthorized'

  /logout:
    post:
      summary: Logout using your credentials
      description: You must provide access token in the request body. When you revoke your tokens, you won't be able to use them for accessing the backend.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                accessToken:
                  type: string
                  example: abc

      responses:
        '200':
          description: Successful operation. Your refresh token was revoked and cannot be used for refreshing tokens anymore until you log in again.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Logout error'

  /users/{username}:
    get:
      summary: Get user info
      description: Information about the user, their rides, cars etc.
      parameters:
        - in: header
          name: Authorization
          description: "Access token. The format should be `Authorization: Bearer <your-token>`"
          required: true
          schema:
            type: string

        - in: path
          name: username
          description: User's name as it appears in the DynamoDB database
          schema:
            type: string
          required: true

      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    type: object
                    properties:
                      username:
                        type: string
                      firstName:
                        type: string
                      roles:
                        type: array
                        items:
                          type: string
                        example: [ "driver", "carProvider" ]
                      availableCars:
                        type: array
                        items:
                          type: string
                        example: [ "ho-123", "renault-789" ]
                      providedCars:
                        type: array
                        items:
                          type: string
                        example: [ "renault-789" ]
                      settings:
                        $ref: '#/components/schemas/Settings'


        '401':
          description: Unauthorized. Invalid credentials presented.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Invalid credentials provided'

    patch:
      summary: Update user data
      description: Update user data like settings etc.
      parameters:
        - in: header
          name: Authorization
          description: "Access token. The format should be `Authorization: Bearer <your-token>`"
          required: true
          schema:
            type: string

        - in: path
          name: username
          description: User's email
          schema:
            type: string
          required: true

      requestBody:
        required: true
        description: Partial settings object is also possible in one request
        content:
          application/json:
            schema:
              type: object
              properties:
                settings:
                  $ref: '#/components/schemas/Settings'

      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    type: object
                    properties:
                      username:
                        type: string
                      firstName:
                        type: string
                      roles:
                        type: array
                        items:
                          type: string
                        example: [ "driver", "carProvider" ]
                      availableCars:
                        type: array
                        items:
                          type: string
                        example: [ "ho-123", "renault-789" ]
                      providedCars:
                        type: array
                        items:
                          type: string
                        example: [ "renault-789" ]
                      settings:
                        $ref: '#/components/schemas/Settings'


        '401':
          description: Unauthorized. Invalid credentials presented.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Invalid credentials provided'

  /bookings/finish/id:
    post:
      summary: Finish ride
      description: Finish one ride of a user
      parameters:
        - in: header
          name: Authorization
          description: "Access token. The format should be `Authorization: Bearer <your-token>`"
          required: true
          schema:
            type: string
        - in: query
          name: username
          description: User's name as it appears in the DynamoDB database
          example: maria@mail.com
          schema:
            type: string
          required: true
        - in: query
          name: carId
          example: ho-123456
          description: User's car id (license plate)
          required: true
          schema:
            type: string
        - in: query
          name: startTime
          example: 1659716808
          description: Timestamp (seconds, not JS milliseconds) of the booking start time
          required: true
          schema:
            type: string

      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                rideCompletionText:
                  type: string
                  example: abc
                  required: true
                endDateTime:
                  type: number
                  example: 12345678
                  required: false
      responses:
        '200':
          description: Successfully finished the ride
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: Finished ride successfully
        '400':
          description: Bad request. You did not provide the necessary information for a successful finish of the ride.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Bad Request'
        '401':
          description: Unauthorized. You likely did not supply the user's access token. The token should be valid and not expired.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Unauthorized'
        '403':
          description: Forbidden. You probably tried to modify someone else's data.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Forbidden'
        '500':
          description: Server-side error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Error finishing the ride'

  /bookings/id:
    get:
      summary: Get booking by ID
      description: Information about the booking
      parameters:
        - in: query
          name: username
          description: User's name as it appears in the DynamoDB database
          example: ilya_nice
          schema:
            type: string
          required: true
        - in: query
          name: carId
          example: ho-123456
          description: User's car id (license plate)
          required: true
          schema:
            type: string
        - in: query
          name: startTime
          example: 1659716808
          description: Timestamp (seconds, not JS milliseconds) of the booking start time
          required: true
          schema:
            type: string
        - in: header
          name: Authorization
          description: "Access token. The format should be `Authorization: Bearer <your-token>`"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  booking:
                    type: object
                    properties:
                      bookingOwner:
                        type: object
                        properties:
                          username:
                            type: string
                          firstName:
                            type: string
                          sessionId:
                            type: string
                          roles:
                            type: array
                            items:
                              type: string
                            example: [ "driver", "carProvider" ]
                          availableCars:
                            type: array
                            items:
                              type: string
                            example: [ "ho-123", "renault-789" ]
                          providedCars:
                            type: array
                            items:
                              type: string
                            example: [ "renault-789" ]
                          settings:
                            $ref: '#/components/schemas/Settings'
                      bookingOwnerId:
                        type: string
                        example: "ilya_nice"
                      carNumber:
                        type: string
                        example: "ho-123456"
                      bookingStartTime:
                        type: string
                        example: "2022-10-02T19:27:43.000Z"
                      bookingDescription:
                        type: string
                        example: "Поездка в Новолукомль"
        '401':
          description: Unauthorized. Invalid credentials presented.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Unauthorized'
        '404':
          description: Not Found. Do not rely on the wording of these errors! They may change on the backend side any time. Look at error codes. Check if your fetching library throws an error on response code 500 or still considers it a success and never goes to the `catch` part of the `try/catch` clause.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Could not find booking by ID'
        '500':
          description: Server side error. Do not rely on the wording of these errors! They may change on the backend side any time.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Error getting booking details'

    patch:
      summary: Edit a booking
      description: Edit a new booking by supplying field that you want to change
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                startDateTime:
                  type: number
                  example: 1666439360
                  description: "New timestamp in seconds (!). Warning: providing Javascript milliseconds does not work!"
                  required: false
                endDateTime:
                  type: number
                  example: 1666439360
                  description: "New timestamp of the end of ride in seconds. It is not required when creating a booking, but could be provided if known"
                  required: false
                description:
                  type: string
                  description: New name of your ride
                  required: false
      parameters:
        - in: header
          name: Authorization
          description: "Access token. The format should be `Authorization: Bearer <your-token>`"
          required: true
          schema:
            type: string
        - in: query
          name: username
          description: User's name as it appears in the DynamoDB database
          example: maria@mail.com
          schema:
            type: string
          required: true
        - in: query
          name: carId
          example: ho-123456
          description: User's car id (license plate)
          required: true
          schema:
            type: string
        - in: query
          name: startTime
          example: 1659716808
          description: Timestamp (seconds, not JS milliseconds) of the booking start time
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful edit
          content:
            application/json:
              schema:
                type: object
                properties:
                  booking:
                    type: object
                    properties:
                      bookingOwnerId:
                        type: string
                        example: mary@gmail.com
                      carNumber:
                        type: string
                        example: "ho-123456"
                      bookingStartTime:
                        type: string
                        example: "2022-10-29T13:47:44.000Z"
                      bookingDescription:
                        type: string
                        example: Masha - visit parents
        '400':
          description: Bad request. You did not provide the necessary information the successful editing of the booking.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Bad Request'
        '401':
          description: Unauthorized. You likely forgot to include the cookie in the request, or the cookie is incorrect.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Unauthorized'
        '404':
          description: Booking not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Could not find booking by ID'
        '500':
          description: Server side error. Do not rely on the wording of these errors! They may change on the backend side any time.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Error saving your booking'

    delete:
      summary: Delete ride
      description: Delete one ride of a user
      parameters:
        - in: header
          name: Authorization
          description: "Access token. The format should be `Authorization: Bearer <your-token>`"
          required: true
          schema:
            type: string
        - in: query
          name: username
          description: User's name as it appears in the DynamoDB database
          example: maria@mail.com
          schema:
            type: string
          required: true
        - in: query
          name: carId
          example: ho-123456
          description: User's car id (license plate)
          required: true
          schema:
            type: string
        - in: query
          name: startTime
          example: 1659716808
          description: Timestamp (seconds, not JS milliseconds) of the booking start time
          required: true
          schema:
            type: string

      responses:
        '200':
          description: Successfully deleted the booking
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: Booking removed
        '400':
          description: Bad request. You did not provide the necessary information for a successful deletion of the booking.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Bad Request'
        '401':
          description: Unauthorized. You likely did not supply the user's access token. The token should be valid and not expired.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Unauthorized'
        '500':
          description: Server-side error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Error getting booking details'

  /bookings:
    get:
      summary: Get all bookings by some criterion (car, user etc.)
      description: List of bookings for a particular car or a particular user. For example, for family Honda, this should return a list of all bookings, including created by Masha, Ilya and Papa.
        
        
        When `username` is included in query params together with `carId`, then user details are also returned
      parameters:
        - in: query
          name: carId
          example: ho-123456
          description: User's car id (license plate)
          required: true
          schema:
            type: string
        - in: query
          name: username
          example: masha@mail.com
          description: User's name, if you want to refine the search to find only the rides for a particular user
          required: false
          schema:
            type: string
        - in: header
          name: Authorization
          description: "Access token. The format should be `Authorization: Bearer <your-token>`"
          required: true
          schema:
            type: string

      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  bookings:
                    type: array
                    items:
                      type: object
                      properties:
                        bookingOwnerId:
                          type: string
                          example: mariya_kalib
                        carNumber:
                          type: string
                          example: "ho-123456"
                        bookingStartTime:
                          type: string
                          example: "2022-10-19T13:47:44.000Z"
                        bookingDescription:
                          type: string
                          example: Masha - visit parents
        '401':
          description: Unauthorized. You either gave a car number that the current user cannot access, or you forgot to include the Authorization header in the request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Unauthorized'
        '404':
          description: Bookings not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Could not find booking by ID'
        '500':
          description: Server side error. Do not rely on the wording of these errors! They may change on the backend side any time.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Error getting booking details'
    post:
      summary: Create a booking
      description: Create a new booking by supplying required parameters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                username:
                  type: string
                  example: masha@mail.com
                  required: true
                carId:
                  type: string
                  example: ho-123456
                  required: true
                startDateTime:
                  type: number
                  example: 1666439360
                  description: "Timestamp in seconds (!). Warning: providing Javascript milliseconds does not work!"
                  required: true
                endDateTime:
                  type: number
                  example: 1666439360
                  description: "Timestamp of the end of ride in seconds. It is not required when creating a booking, but could be provided if known"
                  required: false
                description:
                  type: string
                  description: Name of your ride
                  required: false
      parameters:
        - in: header
          name: Authorization
          description: "Access token. The format should be `Authorization: Bearer <your-token>`"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  booking:
                    type: object
                    properties:
                      bookingOwnerId:
                        type: string
                        example: mariya_kalib
                      carNumber:
                        type: string
                        example: "ho-123456"
                      bookingStartTime:
                        type: string
                        example: "2022-10-29T13:47:44.000Z"
                      bookingDescription:
                        type: string
                        example: New title of your booking
        '401':
          description: Unauthorized. You likely forgot to include the cookie in the request, or the cookie is incorrect.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Unauthorized'
        '404':
          description: Bookings not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Could not find booking by ID'
        '500':
          description: Server side error. Do not rely on the wording of these errors! They may change on the backend side any time.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Error saving your booking'

  /account:
    delete:
      summary: Delete user account by credentials
      description: Delete the user's account and their rides and information. Sign up once again to create a new user
      parameters:
        - in: header
          name: Authorization
          description: "Access token. The format should be `Authorization: Bearer <your-token>`"
          required: true
          schema:
            type: string

      responses:
        '200':
          description: Successfully deleted the user
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: User removed
        '401':
          description: Unauthorized. You likely did not supply the user's access token. The token should be valid and not expired.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Unauthorized'
        '500':
          description: Server-side error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'Error getting booking details'


components:
  schemas:
    Settings:
      type: object
      properties:
        rideCompletionText:
          type: string
          example: 'Машина в гараже'
        notifications:
          type: object
          properties:
            getNotifiedWhenBookingChanged:
              type: boolean
            getNotifiedWhenBookingCreated:
              type: boolean
              example: false