openapi.yaml

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Cryptour API
  license:
    name: SWE 2022
    
servers:
  - url: https://backend.cryptour.dullmer.de/
  - url: http://localhost:3030
tags:
  - name: Tours
    description: >-
      Tours are the core Dataset of the API. They describe a planned 
      hiking route and can be created, sold and bought through the planned
      crypto implementation 
  - name: Users
    description: >-
      A user can be a provider or consumer of a tour. 
paths:
  /tours:
    get:
      summary: List all tours
      operationId: listTours
      tags:
        - Tours
      parameters:
        - name: searchQuery
          in: query
          description: Search by title of the tour
          required: false
          schema:
            type: string
        - name: minDifficulty
          in: query
          description: Search by minimum tour difficulty
          required: false
          schema:
            type: integer
            format: int32
        - name: maxDifficulty
          in: query
          description: Search by maximum tour difficulty
          required: false
          schema:
            type: integer
            format: int32
        - name: minDistance
          in: query
          description: Search by minimum tour length
          required: false
          schema:
            type: integer
            format: int32
        - name: maxDistance
          in: query
          description: Search by maximum tour length
          required: false
          schema:
            type: integer
            format: int32
        - name: minDuration
          in: query
          description: Search by minimum tour time 
          required: false
          schema:
            type: integer
            format: int32
        - name: maxDuration
          in: query
          description: Search by maximum tour time 
          required: false
          schema:
            type: integer
            format: int32
        - name: location
          in: query
          description: Search by tour location
          required: false
          schema:
            type: string
      responses:
        200:
          description: An array of tours
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Tours"
          headers:
            NumberOfResults:
              schema:
                type: number
              description: "How many Tours were found"
        400:
          description: malformed query input
          content:
            application/json:
              schema:
                type: object
                properties:
                    Error: 
                      type: string
                      example: Expected Number for {Queryparameter}

    post:
      summary: Create a tour
      operationId: createTour
      tags:
        - Tours
      security:
        - basicAuth: []
        - cookieAuth: []
      requestBody:
        description: A description of a Tour
        required: true
        content:
          application/json:
            schema: 
              $ref: "#/components/schemas/TourCreate"
      responses:
        200:
          description: Tour successfully created
          content: 
            application/json:
              schema:
                type: object
                properties:
                  tID: 
                    type: number
                    example: 5
                    description: resulting tour id
        400:
          description: tour is not correctly formatted
          content:
            application/json:
              schema:
                type: object
                properties:
                  Error:
                    type: string
                    example: body is not properly formatted! Please reference the YAML
        401:
          $ref: "#/components/responses/UnauthorizedError"
  /tours/{TID}:
    get:
      summary: Get a specific tour
      operationId: getTour
      tags:
        - Tours
      parameters:
        - name: TID
          in: path
          required: true
          description: The ID of the tour to retrieve
          schema:
            type: integer
            format: int64
      responses:
        200:
          description: Tour found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Tour"
        400:
          description: no TID Parameter given
          content:
            application/json:
              schema:
                type: object
                properties:
                  Error: 
                    type: string
                    example: Expected Number for TID  
        404:
          description: Tour not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  Error:
                    type: string
                    example: Could not find tour with id {TID}

    delete:
      summary: Delete a specific tour
      operationId: deleteTour
      tags:
        - Tours
      security:
        - basicAuth: []
        - cookieAuth: []
      parameters:
        - name: TID
          in: path
          required: true
          description: The ID of the tour to delete
          schema:
            type: integer
            format: int64
      responses:
        204:
          description: Tour deleted
        401:
          $ref: "#/components/responses/UnauthorizedError"
        403:
          description: User does not own tour or tour already bought by someone. Unable to delete.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Error:
                    type: string
                    example: Tour is already bought and therefore cannot be deleted
        404:
          description: Tour not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  Error:
                    type: string
                    example: Could not find Tour
  /tours/{TID}/image:
    post:
      summary: Upload an image file
      operationId: uploadImage
      tags:
        - Tours
      security:
        - basicAuth: []
        - cookieAuth: []
      parameters:
        - name: TID
          in: path
          required: true
          description: The ID of the tour to delete
          schema:
            type: integer
            format: int64
      requestBody:
        description: The Image file
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        201:
          description: Image successfully uploaded
        400:
          description: unexpected error when uploading image
        401:
          $ref: "#/components/responses/UnauthorizedError"

  /tours/{TID}/image/{IID}:
    get:
      summary: Get a tour image
      operationId: getTourImage
      tags:
        - Tours
      parameters:
        - name: TID
          in: path
          required: true
          description: The ID of the tour
          schema:
            type: integer
            format: int64
        - name: IID
          in: path
          required: true
          description: The ID of the image to retrieve
          schema:
            type: integer
            format: int64
      responses:
        200:
          description: Tour Image returned
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
        404:
          description: image not found
          content:
            application/json:
              schema:
                type: string
                example: Could not find image with ID {IID} for tour with ID {TID}

  /tours/{TID}/gpx:
    get:
      summary: Get a tour gpx file
      operationId: getTourGPX
      tags:
        - Tours
      security:
        - basicAuth: []
        - cookieAuth: []
      parameters:
        - name: TID
          in: path
          required: true
          description: The ID of the tour to retrieve
          schema:
            type: integer
            format: int64
      responses:
        200:
          description: Tour GPX returned
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        401:
          $ref: "#/components/responses/UnauthorizedError"
        403:
          description: user has not bought tour
          content:
            application/json:
              schema:
                type: string
                example: User not allowed to download gpx file
        404:
          description: GPX not found
          content:
            application/json:
              schema:
                type: string
                example: Could not find GPX Data for Tour with ID {TID}
    post:
      summary: Upload a gpx file
      operationId: uploadGPX
      tags:
        - Tours
      security:
        - basicAuth: []
      parameters:
        - name: TID
          in: path
          required: true
          description: The ID of the tour to delete
          schema:
            type: integer
            format: int64
      requestBody:
        description: The GPX file
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        201:
          description: GPX successfully uploaded
        400:
          description: unexpected when uploading gpx file
        401:
          $ref: "#/components/responses/UnauthorizedError"

  /tours/{TID}/rating:
    post:
      summary: Rate a tour
      operationId: rateTour
      security:
        - basicAuth: []
        - cookieAuth: []
      parameters:
        - name: TID
          in: path
          required: true
          description: The ID of the tour to retrieve
          schema:
            type: integer
            format: int64
      requestBody:
        description: The rating from 1 to 5
        required: true
        content:
          application/json:
            schema: 
              $ref: "#/components/schemas/Rating"
      tags:
        - Tours
      responses:
        200:
          description: Rating added or updated
        401:
          $ref: "#/components/responses/UnauthorizedError"
        404:
          description: Tour not found
          content:
            application/json:
              schema: 
                type: string
                example: wrong tid
        406:
          description: Rating not between 1 and 5
          content:
            application/json:
              schema: 
                type: string
                example: int value between 1 and 5 allowed
        500:
          description: unexpected error
    get:
      summary: Get a tour rating
      operationId: getTourRating
      tags:
        - Tours
      parameters:
        - name: TID
          in: path
          required: true
          description: The ID of the tour to retrieve
          schema:
            type: integer
            format: int64
      responses:
        200:
          description: Tour Rating returned
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Rating"
          headers:
            NumberOfResults:
              schema:
                type: integer
                description: Number of submitted ratings
        400:
          description: unexpected error
          content:
            application/json:
              schema:
                type: object
                properties:
                  Error:
                    type: string
                    example: no ratings submitted for this tour
        404:
          description: tour not found
          content:
            application/json:
              schema:
                type: string
                example: "Error: Could not Find Tour with ID {TID}"
  /tours/{TID}/creator:
    get:
      summary: Get the creator username of this tour
      operationId: getCreatorName
      tags:
        - Tours
      responses:
        200:
          description: Successful request
          content:
            text/plain:
              schema:
                type: string
                example: user1
        404:
          description: tour not found
          content:
            text/plain:
              schema:
                type: string
                example: "Error: Could not Find Tour with ID {TID}"
      
  /user:
    get:
      summary: Get info about myself
      operationId: getUser
      tags:
        - Users
      security:
        - basicAuth: []
        - cookieAuth: []
      responses:
        200:
          description: Successful request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        400:
          description: unexpected error
        401:
          $ref: "#/components/responses/UnauthorizedError"
    post:
      summary: Create a new User
      operationId: createUser
      tags:
        - Users
      requestBody:
        description: The user information
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserRegister"
      responses:
        201:
          description: User successfully created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        400:
          description: user supplied cannot be created
          content:
            application/json:
              schema:
                type: string
                example: unknown error
    patch:
      summary: Edit the information of an existing user
      operationId: patchUser
      tags:
        - Users
      security:
        - basicAuth: []
        - cookieAuth: []
      requestBody:
        description: The user information
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserRegister"
      responses:
        201:
          description: User successfully created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        400:
          description: unexpected error
        401:
          $ref: "#/components/responses/UnauthorizedError"
        500:
          description: unexpected error
  /user/createdTours:
    get:
      summary: Get my created tours
      operationId: getCreatedTours
      tags:
        - Users
      security:
        - basicAuth: []
        - cookieAuth: []
      responses:
        200:
          description: Tour found
          content:
            application/json:
              schema:
                type: array
                items:
                  type: number
        400:
          description: unexpected error
        401:
          $ref: "#/components/responses/UnauthorizedError"
  /user/boughtTours:
    get:
      summary: Get my bought tours
      operationId: getBoughtTours
      tags:
        - Users
      security:
        - basicAuth: []
        - cookieAuth: []
      responses: 
        200:
          description: Bought tours
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Tour"
        401:
          $ref: "#/components/responses/UnauthorizedError"
        500:
          description: unexpected error
  /user/connectWallet:
    post:
      summary: Create a new User
      operationId: connectWallet
      tags:
        - Users
      security:
        - basicAuth: []
        - cookieAuth: []
      requestBody:
        description: The user wallet id on the Ethereum chain
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WalletConnect"
      responses:
        201:
          description: Wallet successfully connected
        401:
          $ref: "#/components/responses/UnauthorizedError"
        400:
          description: unexpected error
  /user/#:
    post:
      summary: Log in user and receive session cookie
      tags:
        - Users
      security:
        - basicAuth: []
      responses:
        200:
          description: user successfully logged in
        401:
          $ref: "#/components/responses/UnauthorizedError"
        400:
          description: unexpected error

  /user/logout:
    post:
      summary: destroy session cookie
      tags:
        - Users
      security:
        - cookieAuth: []
      responses:
        200:
          description: sessioncookie successfully destroyed
        401:
          description: couldn't destroy session cookie
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: sessioncookie couldn't be destroyed!
        400:
          description: unexpected error
  /user/loggedin:
    get:
      summary: check if the user is logged in
      tags:
        - Users
      security:
        - cookieAuth: []
      responses:
        200:
          description: user logged in
        401:
          description: not logged in
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: not logged in
        400:
          description: client not logged in
  /user/updatePassword:
    patch:
      summary: update the user password
      tags:
        - Users
      security:
        - basicAuth: []
        - cookieAuth: []
      responses:
        201:
          description: password successfully updated
        401:
          description: unexpected error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: unexpected error
        400:
          description: unexpected error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: unexpected error


components:
  schemas:
    User:
      required:
        - firstname
        - surname
        - email
        - username
      properties:
        id:
          type: integer
          format: int64
        firstname:
          type: string
        surname:
          type: string
        username:
          type: string
        email:
          type: string
          format: email
        walletID:
          type: string
    UserRegister:
      required:
        - firstname
        - surname
        - email
        - username
        - password
      properties:
        firstname:
          type: string
        surname:
          type: string
        username:
          type: string
        password:
          type: string
        email:
          type: string
          format: email
        wallet-id:
          type: string
    Tour:
      properties:
        title:
          type: string
        difficulty:
          type: integer
          format: int32
        location:
          type: string
        distance:
          type: number
        duration:
          type: number
        description:
          type: string
        creatorID:
          type: string
        tourImages:
          type: array
          items:
            type: object
            properties:
              tiID:
                type: string
    TourCreate:
      properties:
        title:
          type: string
        difficulty:
          type: integer
          format: int32
        location:
          type: string
        distance:
          type: number
        duration:
          type: number
        description:
          type: string
    Tours:
      type: array
      items:
        $ref: "#/components/schemas/Tour"
    Rating:
      required:
        - rating
      properties:
        rating:
          type: integer
    WalletConnect:
      properties:
        walletAddress:
          type: string
    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
  responses:
    UnauthorizedError:
      description: Authentication information is missing or invalid
      content:
        application/json:
          schema: 
            type: string
            example: Invalid Credentials
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    cookieAuth:
      type: apiKey
      in: cookie
      name: SessionID