openapi-config-api.yaml

openapi: "3.0.1"

info:
  title: Event Gateway - Configuration API
  version: "0.8.1"
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  contact:
    name: Serverless, Inc.
    url: http://www.serverless.com

servers:
- url: http://localhost:4001/{basePath}
  description: Locally running Event Gateway
  variables:
    basePath:
      default: v1

tags:
- name: "event type"
  description: "Operations about event types"
- name: "function"
  description: "Operations about functions"
- name: "subscription"
  description: "Operations about subscriptions"
- name: "cors"
  description: "Operations about CORS"

paths:
  /spaces/{spaceName}/eventtypes:
    summary: "Operations about event types"
    get:
      summary: "List event types"
      tags:
      - "event type"
      operationId: "ListEventTypes"
      parameters:
      - $ref: "#/components/parameters/Space"
      - $ref: "#/components/parameters/Filters"
      responses:
        200:
          description: "event types returned"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventTypes"
        500:
          $ref: '#/components/responses/Error'
    post:
      summary: "Create event type"
      tags:
      - "event type"
      operationId: "CreateEventType"
      parameters:
      - $ref: "#/components/parameters/Space"
      requestBody:
        $ref: "#/components/requestBodies/CreateEventType"
      responses:
        201:
          description: "event type created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventType"
        400:
          $ref: '#/components/responses/ValidationError'
        500:
          $ref: '#/components/responses/Error'

  /spaces/{spaceName}/eventtypes/{eventTypeName}:
    summary: "Operations about single event type"
    get:
      summary: "Get event type"
      tags:
      - "event type"
      operationId: "GetEventType"
      parameters:
      - $ref: "#/components/parameters/Space"
      - $ref: "#/components/parameters/EventTypeName"
      responses:
        200:
          description: "event type returned"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventType"
        404:
          $ref: '#/components/responses/NotFoundError'
        500:
          $ref: '#/components/responses/Error'
    put:
      summary: "Update event type"
      tags:
      - "event type"
      operationId: "UpdateEventType"
      parameters:
      - $ref: "#/components/parameters/Space"
      - $ref: "#/components/parameters/EventTypeName"
      requestBody:
        $ref: "#/components/requestBodies/UpdateEventType"
      responses:
        200:
          description: "event type updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventType"
        400:
          $ref: '#/components/responses/ValidationError'
        404:
          $ref: '#/components/responses/NotFoundError'
        500:
          $ref: '#/components/responses/Error'
    delete:
      summary: "Delete event type"
      tags:
      - "event type"
      operationId: "DeleteEventType"
      parameters:
      - $ref: "#/components/parameters/Space"
      - $ref: "#/components/parameters/EventTypeName"
      responses:
        204:
          description: "event type deleted"
        400:
          $ref: '#/components/responses/EventTypeHasSubscriptionsError'
        404:
          $ref: '#/components/responses/NotFoundError'
        500:
          $ref: '#/components/responses/Error'

  /spaces/{spaceName}/functions:
    summary: "Operations about functions"
    get:
      summary: "List functions"
      tags:
      - "function"
      operationId: "ListFunctions"
      parameters:
      - $ref: "#/components/parameters/Space"
      - $ref: "#/components/parameters/Filters"
      responses:
        200:
          description: "functions returned"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Functions"
        500:
          $ref: '#/components/responses/Error'
    post:
      summary: "Register function"
      tags:
      - "function"
      operationId: "CreateFunction"
      parameters:
      - $ref: "#/components/parameters/Space"
      requestBody:
        $ref: "#/components/requestBodies/CreateFunction"
      responses:
        201:
          description: "function registered"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Function"
        400:
          $ref: '#/components/responses/ValidationError'
        500:
          $ref: '#/components/responses/Error'

  /spaces/{spaceName}/functions/{functionId}:
    summary: "Operations about single function"
    get:
      summary: "Get function"
      tags:
      - "function"
      operationId: "GetFunction"
      parameters:
      - $ref: "#/components/parameters/Space"
      - $ref: "#/components/parameters/FunctionID"
      responses:
        200:
          description: "function returned"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Function"
        404:
          $ref: '#/components/responses/NotFoundError'
        500:
          $ref: '#/components/responses/Error'
    put:
      summary: "Update function"
      tags:
      - "function"
      operationId: "UpdateFunction"
      parameters:
      - $ref: "#/components/parameters/Space"
      - $ref: "#/components/parameters/FunctionID"
      requestBody:
        $ref: "#/components/requestBodies/UpdateFunction"
      responses:
        200:
          description: "function updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Function"
        400:
          $ref: '#/components/responses/ValidationError'
        404:
          $ref: '#/components/responses/NotFoundError'
        500:
          $ref: '#/components/responses/Error'
    delete:
      summary: "Delete function"
      tags:
      - "function"
      operationId: "DeleteFunction"
      parameters:
      - $ref: "#/components/parameters/Space"
      - $ref: "#/components/parameters/FunctionID"
      responses:
        204:
          description: "function deleted"
        400:
          $ref: '#/components/responses/FunctionHasSubscriptionsError'
        404:
          $ref: '#/components/responses/NotFoundError'
        500:
          $ref: '#/components/responses/Error'

  /spaces/{spaceName}/subscriptions:
    summary: "Operations about subscriptions"
    get:
      summary: "List subscriptions"
      tags:
      - "subscription"
      operationId: "ListSubscriptions"
      parameters:
      - $ref: "#/components/parameters/Space"
      - $ref: "#/components/parameters/Filters"
      responses:
        200:
          description: "subscriptions returned"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Subscriptions"
        500:
          $ref: '#/components/responses/Error'
    post:
      summary: "Create subscription"
      tags:
      - "subscription"
      operationId: "CreateSubscription"
      parameters:
      - $ref: "#/components/parameters/Space"
      requestBody:
        $ref: "#/components/requestBodies/CreateSubscription"
      responses:
        201:
          description: "subscription created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Subscription"
        400:
          $ref: '#/components/responses/ValidationError'
        500:
          $ref: '#/components/responses/Error'

  /spaces/{spaceName}/subscription/{subscriptionId}:
    summary: "Operations about single subscription"
    get:
      summary: "Get subscription"
      tags:
      - "subscription"
      operationId: "GetSubscription"
      parameters:
      - $ref: "#/components/parameters/Space"
      - $ref: "#/components/parameters/SubscriptionID"
      responses:
        200:
          description: "subscription returned"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Subscription"
        404:
          $ref: '#/components/responses/NotFoundError'
        500:
          $ref: '#/components/responses/Error'
    put:
      summary: "Update subscription"
      tags:
      - "subscription"
      operationId: "UpdateSubscription"
      parameters:
      - $ref: "#/components/parameters/Space"
      - $ref: "#/components/parameters/SubscriptionID"
      requestBody:
        $ref: "#/components/requestBodies/UpdateSubscription"
      responses:
        200:
          description: "subscription updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Subscription"
        400:
          $ref: '#/components/responses/ValidationError'
        404:
          $ref: '#/components/responses/NotFoundError'
        500:
          $ref: '#/components/responses/Error'
    delete:
      summary: "Delete subscription"
      tags:
      - "subscription"
      operationId: "DeleteSubscription"
      parameters:
      - $ref: "#/components/parameters/Space"
      - $ref: "#/components/parameters/SubscriptionID"
      responses:
        204:
          description: "subscription deleted"
        404:
          $ref: '#/components/responses/NotFoundError'
        500:
          $ref: '#/components/responses/Error'

  /spaces/{spaceName}/cors:
    summary: "Operations about CORS configuration"
    get:
      summary: "List CORS configurations"
      tags:
      - "cors"
      operationId: "ListCORS"
      parameters:
      - $ref: "#/components/parameters/Space"
      - $ref: "#/components/parameters/Filters"
      responses:
        200:
          description: "CORS configurations returned"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CORSes"
        500:
          $ref: '#/components/responses/Error'
    post:
      summary: "Create CORS configuration"
      tags:
      - "cors"
      operationId: "CreateCORS"
      parameters:
      - $ref: "#/components/parameters/Space"
      requestBody:
        $ref: "#/components/requestBodies/CreateCORS"
      responses:
        201:
          description: "CORS configuration created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CORS"
        400:
          $ref: '#/components/responses/ValidationError'
        500:
          $ref: '#/components/responses/Error'

  /spaces/{spaceName}/cors/{corsId}:
    summary: "Operations about single CORS configuration"
    get:
      summary: "Get CORS configuration"
      tags:
      - "cors"
      operationId: "GetCORS"
      parameters:
      - $ref: "#/components/parameters/Space"
      - $ref: "#/components/parameters/CORSID"
      responses:
        200:
          description: "CORS configuration returned"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CORS"
        404:
          $ref: '#/components/responses/NotFoundError'
        500:
          $ref: '#/components/responses/Error'
    put:
      summary: "Update CORS configuration"
      tags:
      - "cors"
      operationId: "UpdateCORS"
      parameters:
      - $ref: "#/components/parameters/Space"
      - $ref: "#/components/parameters/CORSID"
      requestBody:
        $ref: "#/components/requestBodies/UpdateCORS"
      responses:
        200:
          description: "CORS configuration updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CORS"
        400:
          $ref: '#/components/responses/ValidationError'
        404:
          $ref: '#/components/responses/NotFoundError'
        500:
          $ref: '#/components/responses/Error'
    delete:
      summary: "Delete CORS configuration"
      tags:
      - "cors"
      operationId: "DeleteCORS"
      parameters:
      - $ref: "#/components/parameters/Space"
      - $ref: "#/components/parameters/CORSID"
      responses:
        204:
          description: "CORS configuration deleted"
        404:
          $ref: '#/components/responses/NotFoundError'
        500:
          $ref: '#/components/responses/Error'

components:
  schemas:
    SpaceName:
      type: string
    FunctionID:
      type: string
    SubscriptionID:
      type: string
    CORSID:
      type: string
    SubscriptionType:
      type: string
      enum:
      - async
      - sync
    ProviderType:
      type: string
      description: "function provider"
      enum:
      - awsfirehose
      - awskinesis
      - awslambda
      - awssqs
      - http
    Provider:
      type: object
      description: "function provider configuration"
      oneOf:
      - $ref: '#/components/schemas/AWSFirehose'
      - $ref: '#/components/schemas/AWSKinesis'
      - $ref: '#/components/schemas/AWSLambda'
      - $ref: '#/components/schemas/AWSSQS'
      - $ref: '#/components/schemas/HTTP'
    EventType:
      type: object
      properties:
        space:
          $ref: '#/components/schemas/SpaceName'
        name:
          $ref: '#/components/schemas/EventTypeName'
        authorizerId:
          $ref: '#/components/schemas/FunctionID'
    Function:
      type: object
      properties:
        space:
          $ref: '#/components/schemas/SpaceName'
        functionId:
          $ref: '#/components/schemas/FunctionID'
        type:
          $ref: '#/components/schemas/ProviderType'
        provider:
          $ref: '#/components/schemas/Provider'
    EventTypes:
      type: object
      properties:
        eventTypes:
          type: array
          items:
            $ref: '#/components/schemas/EventType'
    Functions:
      type: object
      properties:
        functions:
          type: array
          items:
            $ref: '#/components/schemas/Function'
    Subscription:
      type: object
      properties:
        space:
          $ref: '#/components/schemas/SpaceName'
        subscriptionId:
          $ref: '#/components/schemas/SubscriptionID'
        type:
          $ref: '#/components/schemas/SubscriptionType'
        eventType:
          $ref: '#/components/schemas/EventType'
        functionId:
          $ref: '#/components/schemas/FunctionID'
        path:
          $ref: '#/components/schemas/Path'
        method:
          $ref: '#/components/schemas/Method'
    Subscriptions:
      type: object
      properties:
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/Subscription'
    CORS:
      type: object
      properties:
        space:
          $ref: '#/components/schemas/SpaceName'
        corsId:
          $ref: '#/components/schemas/CORSID'
        method:
          $ref: '#/components/schemas/Method'
        path:
          $ref: '#/components/schemas/Path'
        allowedOrigins:
          $ref: '#/components/schemas/AllowedOrigins'
        allowedMethods:
          $ref: '#/components/schemas/AllowedMethods'
        allowedHeaders:
          $ref: '#/components/schemas/AllowedHeaders'
        allowCredentials:
          $ref: '#/components/schemas/AllowCredentials'
    CORSes:
      type: object
      properties:
        cors:
          type: array
          items:
            $ref: '#/components/schemas/CORS'
    AWSFirehose:
      type: object
      properties:
        deliveryStreamName:
          $ref: '#/components/schemas/DeliveryStreamName'
        region:
          $ref: '#/components/schemas/Region'
        awsAccessKeyId:
          $ref: '#/components/schemas/AWSAccessKeyId'
        awsSecretAccessKey:
          $ref: '#/components/schemas/AWSSecretAccessKey'
        awsSessionToken:
          $ref: '#/components/schemas/AWSSessionToken'
    AWSKinesis:
      type: object
      properties:
        streamName:
          $ref: '#/components/schemas/StreamName'
        region:
          $ref: '#/components/schemas/Region'
        awsAccessKeyId:
          $ref: '#/components/schemas/AWSAccessKeyId'
        awsSecretAccessKey:
          $ref: '#/components/schemas/AWSSecretAccessKey'
        awsSessionToken:
          $ref: '#/components/schemas/AWSSessionToken'
    AWSLambda:
      type: object
      properties:
        arn:
          $ref: '#/components/schemas/ARN'
        region:
          $ref: '#/components/schemas/Region'
        awsAccessKeyId:
          $ref: '#/components/schemas/AWSAccessKeyId'
        awsSecretAccessKey:
          $ref: '#/components/schemas/AWSSecretAccessKey'
        awsSessionToken:
          $ref: '#/components/schemas/AWSSessionToken'
    AWSSQS:
      type: object
      properties:
        queueUrl:
          $ref: '#/components/schemas/QueueURL'
        region:
          $ref: '#/components/schemas/Region'
        awsAccessKeyId:
          $ref: '#/components/schemas/AWSAccessKeyId'
        awsSecretAccessKey:
          $ref: '#/components/schemas/AWSSecretAccessKey'
        awsSessionToken:
          $ref: '#/components/schemas/AWSSessionToken'
    HTTP:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/URL'
    ARN:
      type: string
      description: "AWS ARN identifier"
    Region:
      type: string
      description: "AWS Region name"
    AWSAccessKeyId:
      type: string
      description: "AWS Access Key ID"
    AWSSecretAccessKey:
      type: string
      description: "AWS Secret Access Key"
    AWSSessionToken:
      type: string
      description: "AWS Session Token"
    StreamName:
      type: string
      description: "AWS Kinesis stream name"
    DeliveryStreamName:
      type: string
      description: "AWS Firehose delivery stream name"
    QueueURL:
      type: string
      description: "AWS SQS Queue URL"
    URL:
      type: string
      format: url
      description: "HTTP endpoint URL"
    EventTypeName:
      type: string
      description: "event type"
    Method:
      type: string
      description: "(only for HTTP event) HTTP method that accepts requests"
    Path:
      type: string
      description: "URL path under which events (HTTP requests) are accepted"
      default: "/"
    AllowedOrigins:
      type: array
      items:
        type: string
    AllowedMethods:
      type: array
      items:
        type: string
    AllowedHeaders:
      type: array
      items:
        type: string
    AllowCredentials:
      type: boolean
    Error:
      type: object
      description: "response error object"
      properties:
        message:
          type: string
    Errors:
      type: object
      description: "error response object"
      properties:
        errors:
          type: array
          items:
            $ref: "#/components/schemas/Error"
  parameters:
    Space:
      in: "path"
      name: "spaceName"
      description: "space name"
      required: true
      schema:
        $ref: "#/components/schemas/SpaceName"
    EventTypeName:
      in: "path"
      name: "eventTypeName"
      description: "event type name"
      required: true
      schema:
        $ref: "#/components/schemas/EventTypeName"
    FunctionID:
      in: "path"
      name: "functionId"
      description: "function identifier"
      required: true
      schema:
        $ref: "#/components/schemas/FunctionID"
    SubscriptionID:
      in: "path"
      name: "subscriptionId"
      description: "subscription identifier"
      required: true
      schema:
        $ref: "#/components/schemas/SubscriptionID"
    CORSID:
      in: "path"
      name: "corsId"
      description: "CORS configuration identifier"
      required: true
      schema:
        $ref: "#/components/schemas/CORSID"
    Filters:
      in: "query"
      name: "filters"
      description: filter out returned list of objects. Currently, filters can only use metadata properties e.g. `metadata.service=usersService`.
      style: form
      example:
        "metadata.service": usersService
      schema:
        type: object
        additionalProperties:
          type: string
  requestBodies:
    CreateEventType:
      description: "event type create request body"
      content:
        application/json:
          schema:
            type: object
            required:
              - name
            properties:
              name:
                $ref: '#/components/schemas/EventTypeName'
              authorizerId:
                $ref: '#/components/schemas/FunctionID'
    UpdateEventType:
      description: "event type update request body"
      content:
        application/json:
          schema:
            type: object
            properties:
              authorizerId:
                $ref: '#/components/schemas/FunctionID'
    CreateFunction:
      description: "function create request body"
      content:
        application/json:
          schema:
            type: object
            required:
              - functionId
              - type
              - provider
            properties:
              functionId:
                $ref: '#/components/schemas/FunctionID'
              type:
                $ref: '#/components/schemas/ProviderType'
              provider:
                $ref: '#/components/schemas/Provider'
    UpdateFunction:
      description: "function update request body"
      content:
        application/json:
          schema:
            type: object
            properties:
              type:
                $ref: '#/components/schemas/ProviderType'
              provider:
                $ref: '#/components/schemas/Provider'
    CreateSubscription:
      description: "subscription create request body"
      content:
        application/json:
          schema:
            type: object
            required:
              - type
              - eventType
              - functionId
            properties:
              type:
                $ref: '#/components/schemas/SubscriptionType'
              eventType:
                $ref: '#/components/schemas/EventType'
              functionId:
                $ref: '#/components/schemas/FunctionID'
              path:
                $ref: '#/components/schemas/Path'
              method:
                $ref: '#/components/schemas/Method'
    UpdateSubscription:
      description: "subscription update request body"
      content:
        application/json:
          schema:
            type: object
            properties:
              type:
                $ref: '#/components/schemas/SubscriptionType'
              eventType:
                $ref: '#/components/schemas/EventType'
              functionId:
                $ref: '#/components/schemas/FunctionID'
              path:
                $ref: '#/components/schemas/Path'
              method:
                $ref: '#/components/schemas/Method'
    CreateCORS:
      description: "CORS configuration create request body"
      content:
        application/json:
          schema:
            type: object
            properties:
              method:
                $ref: '#/components/schemas/Method'
              path:
                $ref: '#/components/schemas/Path'
              allowedOrigins:
                $ref: '#/components/schemas/AllowedOrigins'
              allowedMethods:
                $ref: '#/components/schemas/AllowedMethods'
              allowedHeaders:
                $ref: '#/components/schemas/AllowedHeaders'
              allowCredentials:
                $ref: '#/components/schemas/AllowCredentials'
    UpdateCORS:
      description: "CORS configuration update request body"
      content:
        application/json:
          schema:
            type: object
            properties:
              method:
                $ref: '#/components/schemas/Method'
              path:
                $ref: '#/components/schemas/Path'
              allowedOrigins:
                $ref: '#/components/schemas/AllowedOrigins'
              allowedMethods:
                $ref: '#/components/schemas/AllowedMethods'
              allowedHeaders:
                $ref: '#/components/schemas/AllowedHeaders'
              allowCredentials:
                $ref: '#/components/schemas/AllowCredentials'
  responses:
    Error:
      description: "internal server error"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    NotFoundError:
      description: "not found error"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    ValidationError:
      description: "validation error"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    FunctionHasSubscriptionsError:
      description: "function is subscribed to at least one event"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    EventTypeHasSubscriptionsError:
      description: "there are subscriptions using the event type"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'