flashover.yaml

---
openapi: 3.0.0
info:
  title: A simple message queue over HTTP

tags:
  - name: message
    description: |
      Operations pertaining to messages.

  - name: topic
    description: |
      Operations pertaining to topics of messages.

  - name: group
    description: |
      Operations pertaining to topic consumer groups.

paths:
  /api/v1/topic:
    get:
      tags:
        - topic
      summary: Enumerate available topics
      responses:
        200:
          description: A collection of available topics
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Topics"
    post:
      tags:
        - topic
      summary: Add a new topic
      requestBody:
        description: A topic descriptor to be added
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Topic"
        required: true
      responses:
        200:
          description: Topic created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TopicCreated"
        401:
          description: Unauthorized
          content: {}
        406:
          description: Invalid topic descriptor
          content: {}
        409:
          description: Conflicting topic descriptor
          content: {}

  /api/v1/topic/{topicId}:
    get:
      tags:
        - topic
      summary: Interrogate a topic by name
      parameters:
        - in: path
          name: topicId
          required: true
          description: ID of the topic to interrogate
          schema:
            $ref: "#/components/schemas/IdStr"
      responses:
        200:
          description: The topic status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TopicStatus"

  /api/v1/group:
    get:
      tags:
        - group
      summary: Enumerate available consumer groups
      responses:
        200:
          description: A collection of available consumer (offset) groups
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Groups"
    post:
      tags:
        - group
      summary: Add a new consumer group
      requestBody:
        description: A consumer group descriptor
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Group"
        required: true
      responses:
        200:
          description: Group created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GroupCreated"
        401:
          description: Unauthorized
          content: {}
        406:
          description: Invalid consumer group descriptor
          content: {}
        409:
          description: Conflicting consumer group descriptor
          content: {}

  /api/v1/group/{groupId}:
    get:
      tags:
        - group
      summary: Get details about a specific consumer group by ID.
      description: |
        FIXME

      parameters:
        - name: groupId
          in: path
          required: true
          description: ID of the consumer group to interrogate.
          schema:
            $ref: "#/components/schemas/IdStr"
      responses:
        404:
          description: No such consumer group
          content: {}
        200:
          description: Consumer group details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Group"
    delete:
      tags:
        - group
      summary: Delete a consumer group by ID.
      description: |
        FIXME

      parameters:
        - name: groupId
          in: path
          required: true
          description: ID of the consumer group to delete.
          schema:
            $ref: "#/components/schemas/IdStr"
      responses:
        404:
          description: No such consumer group
          content: {}
        200:
          description: Consumer group deleted.
          content: {}

  /api/v1/message:
    get:
      tags:
        - message
      summary: Fetch messages
      description: |
        Attempt to consume message(s) from a topic, optionally updating a consumer group as a
        side-effect before returning the message(s).

        If an offset is provided, reads the specified {messageCount} of messages starting from the
        provided {messageId}. Note that
      parameters:
        - in: query
          name: topicId
          required: true
          description: ID of the topic(s) to consume from
          explode: true
          schema:
            $ref: "#/components/schemas/IdStr"
        - in: query
          name: consumerId
          description: ID of the consumer group to use when consuming
          schema:
            $ref: "#/components/schemas/IdStr"
        - in: query
          name: consumerAck
          description: Whether to ack messages in the consumer group when consuming
          schema:
            type: boolean
        - in: query
          name: messageId
          description: ID of the message to consume
          schema:
            $ref: "#/components/schemas/IdStr"
        - in: query
          name: messageCount
          description: Number of messages to return
          schema:
            type: integer
      responses:
        200:
          description: A collection describing the read messages
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProducedMessages"
    post:
      tags:
        - message
      summary: Attempt to produce one or more messages in a transaction.
      description: |
        FIXME

      requestBody:
        description: A batch of one or more messages to produce
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UnproducedMessages"
        required: true
      responses:
        200:
          description: Record(s) produced to topic(s)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommitDescriptor"

components:
  schemas:
    Any:
      description: Any JSON value.

    IdStr:
      type: string
      description: URL safe, relatively short IDs
      pattern: "[a-z0-9][a-z0-9_-]+"
      maxLength: 64

    ################################################################################
    # Topics

    ########################################
    # Topic retention
    TTLRetention:
      description: Part of the RetentionPolicy variant.
      type: object
      properties:
        tag:
          type: string
          enum:
            - TTLRetention
        duration:
          type: integer
          description: Milliseconds to retain records

    LengthRetention:
      description: Part of the RetentionPolicy variant.
      type: object
      properties:
        tag:
          type: string
          enum:
            - LengthRetention
        duration:
          type: integer
          description: Number of records to retain

    UnboundedRetention:
      description: Part of the RetentionPolicy variant.
      type: string
      enum:
        - UnboundedRetention

    RetentionPolicy:
      description: |
        A topic retention policy
      oneOf:
        - $ref: "#/components/schemas/TTLRetention"
        - $ref: "#/components/schemas/LengthRetention"
        - $ref: "#/components/schemas/UnboundedRetention"

    ########################################
    # Topics proper
    Topic:
      description: A descriptor for a single topic.
      type: object
      properties:
        id:
          $ref: "#/components/schemas/IdStr"
        retentionPolicy:
          $ref: "#/components/schemas/RetentionPolicy"
        schema:
          type: object

    Topics:
      description: A list of available topics.
      type: array
      items:
        $ref: "#/components/schemas/Topic"

    TopicStatus:
      description: A record used to give the current state of the topic.
      oneOf:
        - $ref: "#/components/schemas/Topic"

    TopicCreated:
      description: A record used to acknowledge the creation of a topic.
      oneOf:
        - $ref: "#/components/schemas/Topic"

    ################################################################################
    # [Consumer] groups
    Group:
      description: A descriptor for a consumer group.
      type: object
      properties:
        id:
          $ref: "#/components/schemas/IdStr"
        topics:
          type: object
          additionalProperties:
            type: string

    Groups:
      description: A list of available consumer groups.
      type: array
      items:
        $ref: "#/components/schemas/Group"

    GroupCreated:
      description: A record used to acknowledge the creation of a consumer group.
      oneOf:
        - $ref: "#/components/schemas/Group"

    ################################################################################
    # Producing messages

    ########################################
    # Messages
    UnproducedMessage:
      summary: A message as provided to us by the user
      description: |
        A message as provided to us by the user. More data will be added when we 'produce' it. Users
        are required to provide a value. A [partitioning] key may be provided, but is largely
        ignored. A mapping of headers may also be provided. Headers are expected to be _short_ (256b
        or less) annotations.

        Users must provide the following headers:
          - topicId
            
        Users may provide the following headers:
          - messageKey

        Implementations must provide the following headers automatically:
          - messageId

        Implementations may provide the following headers:
          - commitId
          - commitTimestamp
      type: object
      properties:
        message:
          $ref: "#/components/schemas/Any"
        headers:
          type: object
          properties:
            messageKey:
              $ref: "#/components/schemas/IdStr"
            topicId:
              $ref: "#/components/schemas/IdStr"
          additionalProperties:
            type: string
            maxLength: 256

    ProducedMessage:
      summary: A message as read back from a topic.
      description: |
        A message as read back from a topic after being produced. As we support reading from
        multiple topics at once, and reading by ID, produced records are fully annotated with the
        topic which contains them and a globally unique ID.

        Annotation with the source topic name allows for multi-topic reads to be demuxed.

        Annotation with the record ID may allow for future point reads.
      type: object
      properties:
        message:
          $ref: "#/components/schemas/Any"
        headers:
          type: object
          properties:
            messageKey:
              $ref: "#/components/schemas/IdStr"
            messageId:
              $ref: "#/components/schemas/IdStr"
            topicId:
              $ref: "#/components/schemas/IdStr"
            commitId:
              $ref: "#/components/schemas/IdStr"
            commitTimestamp:
              type: integer
          additionalProperties:
            type: string
            maxLength: 256

    ########################################
    # Batches of messages
    UnproducedMessages:
      description: A collection of messages yet to be produced to topics.
      type: array
      items:
        $ref: "#/components/schemas/UnproducedMessage"

    CommitDescriptor:
      description: |
        A collection of the commit ID, and the IDs of all committed messages.
        For efficiency, message bodies are not returned to the sender, only confirmation data.

        Note: commitMessages is guranteed to be in the same order as the source messages array, but
        this may be confirmed by cross-checking messageTopic and messageKey
      type: object
      properties:
        commitId:
          type: string
        commitTimestamp:
          type: integer
        commitMessages:
          type: array
          items:
            type: object
            properties:
              messageKey:
                type: string
              messageTopic:
                type: string
              messageId:
                type: string

    ProducedMessages:
      description: A collection of messages read back from topic(s).
      type: array
      items:
        $ref: "#/components/schemas/ProducedMessage"

  securitySchemes:
    petstore_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: http://petstore.swagger.io/oauth/dialog
          scopes:
            write:pets: modify pets in your account
            read:pets: read your pets
    api_key:
      type: apiKey
      name: api_key
      in: header