swagger.yml

swagger: '2.0'
info:
  description: FaaS API documentation
  version: 0.6.5
  title: FaaS API Gateway
  license:
    name: MIT
basePath: /
schemes:
  - http
paths:
  /system/functions:
    get:
      summary: 'Get a list of deployed functions with: stats and image digest'
      description: ''
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: List of deployed functions.
          examples:
            application/json: |-
              [
                {"name":"func_payroll","image":"alexellis2/faas-payroll:latest@sha256:0bc2773613c76d9ee4906bf3887ea2527f135cb7a0d0f430743e7c6712949709","invocationCount":16,"replicas":1},
                {"name":"func_fanclub","image":"alexellis2/fanclub:18-04-2017@sha256:37bb3fabee7e36abab7e6250bb7d13c9ab66e983782b35200470fe2a3aa14daa","invocationCount":1125,"replicas":1}
              ]
    post:
      summary: Deploy a new function.
      description: ''
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: Function to deploy
          required: true
          schema:
            $ref: '#/definitions/CreateFunctionRequest'
      responses:
        '200':
          description: OK
    put:
      summary: Update a function.
      description: ''
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: Function to update
          required: true
          schema:
            $ref: '#/definitions/CreateFunctionRequest'
      responses:
        '200':
          description: OK
    delete:
      summary: Remove a deployed function.
      description: ''
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: Function to delete
          required: true
          schema:
            $ref: '#/definitions/DeleteFunctionRequest'
      responses:
        '200':
          description: OK
        '404':
          description: Function not found in gateway
  /system/alert:
    post:
      summary: 'Event-sink for AlertManager, for auto-scaling'
      description: 'Internal use for AlertManager, requires valid AlertManager alert JSON'
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: Function to delete
          schema:
            type: object
            example: |-
              {"receiver": "scale-up",
                "status": "firing",
                "alerts": [{
                    "status": "firing",
                    "labels": {
                        "alertname": "APIHighInvocationRate",
                        "code": "200",
                        "function_name": "func_nodeinfo",
                        "instance": "gateway:8080",
                        "job": "gateway",
                        "monitor": "faas-monitor",
                        "service": "gateway",
                        "severity": "major",
                        "value": "8.998200359928017"
                    },
                    "annotations": {
                        "description": "High invocation total on gateway:8080",
                        "summary": "High invocation total on gateway:8080"
                    },
                    "startsAt": "2017-03-15T15:52:57.805Z",
                    "endsAt": "0001-01-01T00:00:00Z",
                    "generatorURL": "http://4156cb797423:9090/graph?g0.expr=rate%28gateway_function_invocation_total%5B10s%5D%29+%3E+5\u0026g0.tab=0"
                }],
                "groupLabels": {
                    "alertname": "APIHighInvocationRate",
                    "service": "gateway"
                },
                "commonLabels": {
                    "alertname": "APIHighInvocationRate",
                    "code": "200",
                    "function_name": "func_nodeinfo",
                    "instance": "gateway:8080",
                    "job": "gateway",
                    "monitor": "faas-monitor",
                    "service": "gateway",
                    "severity": "major",
                    "value": "8.998200359928017"
                },
                "commonAnnotations": {
                    "description": "High invocation total on gateway:8080",
                    "summary": "High invocation total on gateway:8080"
                },
                "externalURL": "http://f054879d97db:9093",
                "version": "3",
                "groupKey": 18195285354214864953
              }
      responses:
        '200':
          description: Alert handled successfully
        '500':
          description: Internal error with swarm or request JSON invalid
  '/async-function/{functionName}':
    post:
      summary: 'Invoke a function asynchronously in OpenFaaS'
      description: >-
        ### This endpoint requires the asynchronous stack.
        See https://github.com/openfaas/faas/blob/master/guide/asynchronous.md.
      parameters:
        - in: path
          name: functionName
          description: Function name
          type: string
          required: true
        - in: body
          name: input
          description: (Optional) data to pass to function
          schema:
            type: string
            format: binary
            example:
              '{"hello": "world"}'
          required: false
      responses:
        '202':
          description: Request accepted and queued
        '404':
          description: Requested function not found
        '500':
          description: Internal server error
  '/function/{functionName}':
    post:
      summary: Invoke a function defined in OpenFaaS
      parameters:
        - in: path
          name: functionName
          description: Function name
          type: string
          required: true
        - in: body
          name: input
          description: (Optional) data to pass to function
          schema:
            type: string
            format: binary
            example:
              '{"hello": "world"}'
          required: false
      responses:
        '200':
          description: Value returned from function
        '404':
          description: Function not found
        '500':
          description: Error connecting to function
definitions:
  DeleteFunctionRequest:
    type: object
    properties:
      functionName:
        type: string
        description: Name of deployed function
  CreateFunctionRequest:
    type: object
    properties:
      service:
        type: string
        description: Name of deployed function
      network:
        type: string
        description: 'Docker swarm network, usually func_functions'
      image:
        type: string
        description: Docker image in accessible registry
      envProcess:
        type: string
        description: Process for watchdog to fork
      envVars:
        type: array
        items:
          type: string
        description: Overrides to environmental variables
      secrets:
        type: array
        items:
          type: string
      registryAuth:
        type: string
        description: >-
          Private registry base64-encoded basic auth (as present in
          ~/.docker/config.json)
externalDocs:
  description: More documentation available on Github
  url: 'https://github.com/openfaas/faas'