spec.yml

openapi: "3.1.0"
info:
  title: "Competitor API"
  description: "Web-facing API for the challenge"
  version: "1.0.0"
tags:
  - name: "challenge"
    description: "Operations to be implemented by competitors"

paths:
  /api/offers:
    get:
      summary: "Get offers"
      description: "Gets offers matching specific query parameters"
      operationId: getOffers
      tags:
        - "challenge"
      parameters:
        - name: "regionID"
          in: query
          description: "Region ID for which offers are returned. This includes offers from all subregions of this regionID. See the 'Introduction' Section in the documentation."
          required: true
          schema:
            type: "integer"
            format: "int32"
        - name: "timeRangeStart"
          in: query
          description: "Timestamp (ms since UNIX epoch) from when offers are considered (inclusive)"
          required: true
          schema:
            type: "integer"
            format: "int64"
        - name: "timeRangeEnd"
          in: query
          description: "Timestamp (ms since UNIX epoch) until when offers are considered (inclusive)"
          required: true
          schema:
            type: "integer"
            format: "int64"
        - name: "numberDays"
          in: query
          description: "The number of full days (24h) the car is available within the rangeStart and rangeEnd"
          required: true
          schema:
            type: "integer"
            format: "int32"
            x-go-type: "uint16"
        - name: "sortOrder"
          in: query
          required: true
          description: "The order in which offers are returned. When two offers have the same price, the one with the lexicographical smaller ID is returned first (for both sort orders)."
          schema:
            type: "string"
            enum: ["price-asc", "price-desc"]
        - name: "page"
          in: query
          required: true
          description: "The page number from pagination"
          schema:
            type: "integer"
            format: "int64"
            x-go-type: "uint32"
        - name: "pageSize"
          in: query
          required: true
          description: "The number of offers per page"
          schema:
            type: "integer"
            format: "int64"
            x-go-type: "uint32"
        - name: "priceRangeWidth"
          in: query
          required: true
          description: "The width of the price range blocks in cents"
          schema:
            type: "integer"
            format: "int64"
            x-go-type: "uint32"
        - name: "minFreeKilometerWidth"
          in: query
          required: true
          description: "The width of the min free kilometer in km"
          schema:
            type: "integer"
            format: "int64"
            x-go-type: "uint32"
        - name: "minNumberSeats"
          in: query
          description: "How many seats the returned cars each have"
          required: false
          schema:
            type: "integer"
            format: "int32"
            x-go-type: "uint8"
        - name: "minPrice"
          in: query
          description: "Minimum (inclusive) price the offers have in cent"
          required: false
          schema:
            type: "number"
            format: "int32"
            x-go-type: "uint16"
        - name: "maxPrice"
          in: query
          description: "Maximum (exclusive) price the offers have in cent"
          required: false
          schema:
            type: "number"
            format: "int32"
            x-go-type: "uint16"
        - name: "carType"
          in: query
          required: false
          description: "The car type."
          schema:
            type: "string"
            enum: [small, sports, luxury, family]
        - name: "onlyVollkasko"
          in: query
          required: false
          description: "Whether only offers with vollkasko are returned"
          schema:
            type: "boolean"
        - name: "minFreeKilometer"
          in: query
          required: false
          description: "Minimum number of kilometers that the offer includes for free"
          schema:
            type: "integer"
            format: "int32"
            x-go-type: "uint16"
      responses:
        "200":
          description: "The IDs and data of the offers matching the query parameters. For aggregation results, see the 'Filter and Aggregations'-section in the documentation."
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  offers:
                    type: "array"
                    description: "All offers matching the query, with their IDs and additional data."
                    items:
                      $ref: "#/components/schemas/SearchResultOffer"
                  priceRanges:
                    type: "array"
                    description: "Buckets holding information of the number of offers within a specific price range. The results only includes buckets with at least one offer in that range sorted by start ascendingly. Bucket starts and ends are a multiple of the width."
                    items:
                      $ref: "#/components/schemas/PriceRange"
                  carTypeCounts:
                    $ref: "#/components/schemas/CarTypeCount"
                    description: "The the number of offers with a specific car type."
                  seatsCount:
                    type: "array"
                    description: "Buckets holding information of the number of offers with a specific seat count. The results only includes entries with at least one offer with that seats count sorted by numberSeats ascendingly."
                    items:
                      $ref: "#/components/schemas/SeatsCount"
                  freeKilometerRange:
                    type: "array"
                    description: "Buckets holding information of the number of offers within a specific free kilometer range. The results only includes buckets with at least one offer in that range sorted by the start ascendingly. Bucket starts and ends are a multiple of the width."
                    items:
                      $ref: "#/components/schemas/FreeKilometerRange"
                  vollkaskoCount:
                    $ref: "#/components/schemas/VollkaskoCount"
                required:
                  - offers
                  - priceRanges
                  - carTypeCounts
                  - seatsCount
                  - freeKilometerRange
                  - vollkaskoCount
    post:
      summary: "Create offers"
      description: "Creates multiple offers at once, includes at least one offer."
      operationId: createOffers
      tags:
        - "challenge"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                offers:
                  type: "array"
                  items:
                    $ref: "#/components/schemas/Offer"
      responses:
        "200":
          description: "Offers were created"
    delete:
      summary: "Clean up data"
      description: "Cleans up all old offer data. This excludes the static region data initially provided from S3."
      operationId: cleanupData
      tags:
        - "challenge"
      responses:
        "200":
          description: "Data was cleaned up"

components:
  schemas:
    SearchResultOffer:
      type: object
      properties:
        ID:
          type: string
          format: uuid
          example: "01934a57-7988-7879-bb9b-e03bd4e77b9d"
          description: "The unique identifier of the offer"
        data:
          type: string
          description: "Additional data of the offer, that is not used for filtering. For simplicity, this is just a base64 encoded 256 Byte array"
          format: byte
      required:
        - ID
        - data

    Offer:
      type: object
      properties:
        ID:
          type: string
          format: uuid
          example: "01934a57-7988-7879-bb9b-e03bd4e77b9d"
          description: "The unique identifier of the offer"
        data:
          type: string
          description: "Additional data for the offer, that is not used for filtering. For simplicity, this is just a base64 encoded 256 Byte array"
          format: byte
        mostSpecificRegionID:
          type: integer
          format: int32
          description: "The id of the most specific region the offer belongs to. This is always a leaf node."
          example: 5
        startDate:
          type: integer
          format: int64
          description: "The start date of the offer in ms since UNIX epoch"
          example: 1732104000000
        endDate:
          type: integer
          format: int64
          description: "The end date of the offer in ms since UNIX epoch"
          example: 1732449600000
        numberSeats:
          type: integer
          format: int32
          x-go-type: uint8
          description: "The number of seats the car has"
          example: 5
        price:
          type: integer
          format: int32
          x-go-type: uint16
          description: "The price in cents"
          example: 10000
        carType:
          type: string
          example: "luxury"
          description: "The car types the offer belongs to"
        hasVollkasko:
          type: boolean
          description: "Whether the offer has Vollkasko"
          example: true
        freeKilometers:
          type: integer
          format: int32
          x-go-type: uint16
          description: "The number of kilometers included for free"
          example: 120
      required:
        - ID
        - data
        - mostSpecificRegionID
        - price
        - startDate
        - endDate
        - numberSeats
        - carType
        - hasVollkasko
        - freeKilometers

    PriceRange:
      type: object
      properties:
        start:
          type: integer
          format: int32
          x-go-type: uint16
          description: "The start of the price range in cent"
          example: 10000
        end:
          type: integer
          format: int32
          x-go-type: uint16
          description: "The end of the price range in cent"
          example: 15000
        count:
          type: integer
          format: int64
          x-go-type: uint32
          description: "The number of offers in this price range"
          example: 4
      required:
        - start
        - end
        - count

    CarTypeCount:
      type: object
      properties:
        small:
          type: integer
          format: int64
          x-go-type: uint32
          description: "The number of offers with the car type small"
          example: 1
        sports:
          type: integer
          format: int64
          x-go-type: uint32
          description: "The number of offers with the car type sports"
          example: 2
        luxury:
          type: integer
          format: int64
          x-go-type: uint32
          description: "The number of offers with the car type luxury"
          example: 1
        family:
          type: integer
          format: int64
          x-go-type: uint32
          description: "The number of offers with the car type family"
          example: 0
      required:
        - small
        - sports
        - luxury
        - family

    VollkaskoCount:
      type: object
      properties:
        trueCount:
          type: integer
          format: int64
          x-go-type: uint32
          description: "The number of offers with vollkasko"
          example: 3
        falseCount:
          type: integer
          format: int64
          x-go-type: uint32
          description: "The number of offers without Vollkasko"
          example: 1
      required:
        - trueCount
        - falseCount

    SeatsCount:
      type: object
      properties:
        numberSeats:
          type: integer
          format: int32
          x-go-type: uint8
          description: "The number of seats the cars have"
          example: 5
        count:
          type: integer
          format: int64
          x-go-type: uint32
          description: "The number of offers with the given number of seats"
          example: 4
      required:
        - numberSeats
        - count

    FreeKilometerRange:
      type: object
      properties:
        start:
          type: integer
          format: int32
          x-go-type: uint16
          description: "The start of the free kilometer range"
          example: 100
        end:
          type: integer
          format: int32
          x-go-type: uint16
          description: "The end of the free kilometer range"
          example: 150
        count:
          type: integer
          format: int64
          x-go-type: uint32
          description: "The number of offers in this free kilometer range"
          example: 4
      required:
        - start
        - end
        - count