Pubsub API Definition

pubsub-swagger.yaml

swagger: "2.0"
info:
  description: |
    A simple Pubsub messaging API that allows clients to:
      * Publish messages to a Topic
      * Create Subscriptions to a Topic
      * Pull messages from Subscriptions
      * Acknowledge receipt of the messages delivered to a Subscription.
      
      Example:
      
      POST /publish
      request: { topic: “cars”, message: “mustang” }
      
      POST /subscriptions
      request: { topic: “cars” }
      response: { subscriptionId: “1234” }

      POST /subscriptions
      request: { topic: “cars” }
      response: { subscriptionId: “5678” }


     GET /subscriptions/1234/pull
     response: { messages: [“mustang”] }
     
     POST /publish
     request: { topic: “cars”, payload: “corvette” }
     
     GET /subscriptions/1234/pull
     response: { messages: [“corvette”] }
     
     GET /subscriptions/5678/pull
     response: { messages: [“mustang”, “corvette”] }
     
  version: "0.1.0"
  title: "Pubsub API"
host: "pubsub.example.io"
basePath: "/v1"
tags:
- name: "publisher"
- name: "subscriber"
schemes:
- "http"
paths:
  /publish:
    post:
      tags:
      - "publisher"
      summary: "Publish a message to a Pubsub Topic"
      description: |
        Publishes a message to the given Pubsub topic. If the topic doesn't exist, create it.
      operationId: "publish"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "The publish request body."
        required: true
        schema:
          type: object
          properties: {
            "topic": {
              description: "The name of the topic to publish the message payload to",
              type: string
            },
            "message": {
              description: "The message payload to publish",
              type: string
            }
          }
          example: {
            topic: "cars",
            message: "mustang"
          }
      responses:
        "200":
          description: "An empty response indicating the message was published"
  /subscriptions:
    post:
      tags:
      - "subscriber"
      summary: "Create a new Subscription to a Topic"
      description: "Creates a new Pubsub Subscription to a Topic."
      operationId: "createSubscription"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "The request body"
        required: true
        schema:
          type: object
          properties: {
            "topic": {
              type: string,
              example: "cars",
              description: "The topic to create a subscription to"
            }
          }
      responses:
        "200":
          description: "A unique subscription was created"
          schema:
            type: "object"
            properties: {
              "subscriptionId": {
                type: string,
                example: "1234"
              }
            }
  /subscriptions/{subscriptionId}/pull:
    get:
      tags:
      - "subscriber"
      summary: "Pull one or more messages from a Subscription"
      operationId: "pullMessages"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "path"
        name: "subscriptionId"
        description: "The subscription id to pull messages from"
        required: true
        type: string
      - in: "query"
        name: "count"
        description: "The max number of messages to pull"
        type: number
      responses:
        "200":
          description: "A response containing zero or more messages"
          schema:
            type: "object"
            properties: {
              "messages": {
                type: array,
                items: {
                  type: string,
                  example: "mustang"
                }
              }
            }
  /acknowledge:
    post:
      tags:
      - "subscriber"
      summary: "Acknowledges receipt of a message"
      operationId: "acknowledge"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        required: true
        schema:
          type: object
          properties: {
            "subscriptionId": {
              type: string,
              example: "1234"
            },
            "messageId": {
              type: number
            }
          }
      responses:
        "200":
          description: "Message was acknowledged"