api.yaml

openapi: 3.0.3
info:
  title: Ticketing Server
  description: Ticketing Server
  version: 1.0.0
paths:
  /lineages:
    post:
      operationId: createLineage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LineageCreationRequest"
      responses:
        '200':
          description: Lineage created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LineageCreationResponse"
    get:
      operationId: getLineageByExtId
      parameters:
        - name: extId
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Lineage retrieved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LineageGetResponse"

  /lineages/{lineageId}/tickets:
    post:
      summary: Lease tickets
      description: Lease one or many tickets
      operationId: leaseTicket
      parameters:
        - name: lineageId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TicketLeaseRequest"
      responses:
        '200':
          description: Ticket lease acquired
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TicketLeaseResponse"
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    get:
      operationId: getTickets
      parameters:
          - name: lineageId
            in: path
            required: true
            schema:
              type: string
          - name: ticketExtIds
            in: query
            required: true
            schema:
              type: array
              items:
                type: string
      responses:
        '200':
          description: A list of tickets is returned to the client.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TicketLeaseResponse"
        '404':
          description: Tickets with the given extIds does not have an active or closed lease.

  /lineages/{lineageId}/tickets/{ticketExtId}:
    get:
      operationId: getTicket
      parameters:
        - name: lineageId
          in: path
          required: true
          schema:
            type: string
        - name: ticketExtId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The ticket has an active or closed lease which is returned to the client.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TicketLeaseResponse"
        '404':
          description: The ticket with the given extId does not have an active or closed lease.
    patch:
      operationId: updateTicket
      parameters:
        - name: lineageId
          in: path
          required: true
          schema:
            type: string
        - name: ticketExtId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TicketUpdateRequest"
      responses:
        '204':
          description: Ticket status updated and is either released and nonce will be reassigned or closed.

components:
  schemas:
    LineageCreationRequest:
      type: object
      required:
        - extId
        - maxLeasedNonceCount
      properties:
        extId:
          type: string
          pattern: '^[a-zA-Z0-9/-]*'
        maxLeasedNonceCount:
          type: integer
          minimum: 1
          maximum: 32767
          default: 64
        startLeasingFrom:
          type: integer
          default: 0
          minimum: 0
          maximum: 9223372036854775807

    LineageCreationResponse:
      required:
        - id
        - extId
      properties:
        id:
          type: string
        extId:
          type: string

    LineageGetResponse:
      required:
        - id
        - extId
        - nextNonce
        - leasedNonceCount
        - releasedNonceCount
        - maxLeasedNonceCount
        - maxNonceValue
        - version
      properties:
        id:
          type: string
        extId:
          type: string
        nextNonce:
          type: integer
        leasedNonceCount:
          type: integer
        releasedNonceCount:
          type: integer
        maxLeasedNonceCount:
          type: integer
        maxNonceValue:
          type: integer

    TicketLeaseRequest:
      type: object
      required:
        - extIds
      properties:
        extIds:
          type: array
          items:
            type: string

    TicketLeaseResponse:
      type: object
      properties:
        leases:
          type: array
          items:
            $ref: "#/components/schemas/TicketLease"

    TicketLease:
      type: object
      required:
        - lineageId
        - extId
        - nonce
        - state
      properties:
        lineageId:
          type: string
        extId:
          type: string
        nonce:
          type: integer
        state:
          type: string
          enum:
            - leased
            - closed

    TicketUpdateRequest:
      type: object
      required:
        - state
      properties:
        state:
          type: string
          enum:
            - released
            - closed

    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string