Skip to content
Permalink
master
Switch branches/tags

faas/api-docs/swagger.yml

Go to file
 
 
Cannot retrieve contributors at this time
628 lines (628 sloc) 17 KB
Raw Blame
swagger: '2.0'
info:
description: OpenFaaS API documentation
version: 0.8.12
title: OpenFaaS API Gateway
license:
name: MIT
basePath: /
schemes:
- http
paths:
'/system/functions':
get:
summary: 'Get a list of deployed functions with: stats and image digest'
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: List of deployed functions.
schema:
type: array
items:
$ref: '#/definitions/FunctionListEntry'
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/FunctionDefinition'
responses:
'202':
description: Accepted
'400':
description: Bad Request
'500':
description: Internal Server Error
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/FunctionDefinition'
responses:
'200':
description: Accepted
'400':
description: Bad Request
'404':
description: Not Found
'500':
description: Internal Server Error
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
'400':
description: Bad Request
'404':
description: Not Found
'500':
description: Internal Server Error
'/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: Incoming alert
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: >-
See https://docs.openfaas.com/reference/async/.
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: 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: Not Found
'500':
description: Internal server error
'/system/scale-function/{functionName}':
post:
summary: Scale a function
parameters:
- in: path
name: functionName
description: Function name
type: string
required: true
- in: body
name: input
description: Function to scale plus replica count
schema:
type: string
format: binary
example:
'{"service": "hello-world", "replicas": 10}'
required: false
responses:
'200':
description: Scaling OK
'202':
description: Scaling OK
'404':
description: Function not found
'500':
description: Error scaling function
'/system/function/{functionName}':
get:
summary: Get a summary of an OpenFaaS function
parameters:
- in: path
name: functionName
description: Function name
type: string
required: true
responses:
'200':
description: Function Summary
schema:
$ref: '#/definitions/FunctionListEntry'
'404':
description: Not Found
'500':
description: Internal Server Error
'/system/secrets':
get:
summary: 'Get a list of secret names and metadata from the provider'
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: List of submitted secrets.
schema:
$ref: '#/definitions/SecretName'
post:
summary: Create a new secret.
description: ''
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
description: A new secret to create
required: true
schema:
$ref: '#/definitions/Secret'
responses:
'201':
description: Created
'400':
description: Bad Request
'500':
description: Internal Server Error
put:
summary: Update a secret.
description: ''
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
description: Secret to update
required: true
schema:
$ref: '#/definitions/Secret'
responses:
'200':
description: Ok
'400':
description: Bad Request
'404':
description: Not Found
'405':
description: Method Not Allowed. Secret update is not allowed in faas-swarm.
'500':
description: Internal Server Error
delete:
summary: Remove a secret.
description: ''
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
description: Secret to delete
required: true
schema:
$ref: '#/definitions/SecretName'
responses:
'204':
description: OK
'400':
description: Bad Request
'404':
description: Not Found
'500':
description: Internal Server Error
'/system/logs':
get:
summary: Get a stream of the logs for a specific function
produces:
- application/x-ndjson
parameters:
- in: query
name: name
description: Function name
type: string
required: true
- in: query
name: since
description: Only return logs after a specific date (RFC3339)
type: string
required: false
- in: query
name: tail
description: Sets the maximum number of log messages to return, <=0 means unlimited
type: integer
required: false
- in: query
name: follow
description: When true, the request will stream logs until the request timeout
type: boolean
required: false
responses:
'200':
description: Newline delimited stream of log messages
schema:
$ref: '#/definitions/LogEntry'
'404':
description: Not Found
'500':
description: Internal Server Error
'/system/info':
get:
summary: Get info such as provider version number and provider orchestrator
produces:
- application/json
responses:
'200':
description: Info result
schema:
$ref: '#/definitions/Info'
'404':
description: Provider does not support info endpoint
'500':
description: Internal Server Error
'/healthz':
get:
summary: Healthcheck
responses:
'200':
description: Healthy
'500':
description: Not healthy
securityDefinitions:
basicAuth:
type: basic
definitions:
Info:
type: object
properties:
provider:
type: object
description: The OpenFaaS Provider
properties:
provider:
type: string
example: faas-netes
orchestration:
type: string
example: kubernetes
version:
type: object
description: Version of the OpenFaaS Provider
properties:
commit_message:
type: string
example: Sample Message
sha:
type: string
example: 7108418d9dd6b329ddff40e7393b3166f8160a88
release:
type: string
format: semver
example: 0.2.6
version:
type: object
description: Version of the Gateway
properties:
commit_message:
type: string
example: Sample Message
sha:
type: string
example: 7108418d9dd6b329ddff40e7393b3166f8160a88
release:
type: string
format: semver
example: 0.8.9
arch:
type: string
description: "Platform architecture"
example: "x86_64"
required:
- provider
- version
DeleteFunctionRequest:
type: object
properties:
functionName:
type: string
description: Name of deployed function
example: nodeinfo
required:
- functionName
FunctionDefinition:
type: object
properties:
service:
type: string
description: Name of deployed function
example: nodeinfo
network:
type: string
description: Network, usually func_functions for Swarm (deprecated)
example: func_functions
image:
type: string
description: Docker image in accessible registry
example: functions/nodeinfo:latest
envProcess:
type: string
description: Process for watchdog to fork
example: node main.js
envVars:
type: object
additionalProperties:
type: string
description: Overrides to environmental variables
constraints:
type: array
items:
type: string
description: Constraints are specific to OpenFaaS Provider
example: "node.platform.os == linux"
labels:
description: A map of labels for making scheduling or routing decisions
type: object
additionalProperties:
type: string
example:
foo: bar
annotations:
description: A map of annotations for management, orchestration, events and build tasks
type: object
additionalProperties:
type: string
example:
topics: awesome-kafka-topic
foo: bar
secrets:
type: array
items:
type: string
description: An array of names of secrets that are required to be loaded from the Docker Swarm.
example: "secret-name-1"
registryAuth:
type: string
description: >-
Private registry base64-encoded basic auth (as present in
~/.docker/config.json)
example: dXNlcjpwYXNzd29yZA==
limits:
type: object
properties:
memory:
type: string
example: "128M"
cpu:
type: string
example: "0.01"
requests:
type: object
properties:
memory:
type: string
example: "128M"
cpu:
type: string
example: "0.01"
readOnlyRootFilesystem:
type: boolean
description: Make the root filesystem of the function read-only
required:
- service
- image
- envProcess
FunctionListEntry:
type: object
properties:
name:
description: The name of the function
type: string
example: nodeinfo
image:
description: The fully qualified docker image name of the function
type: string
example: functions/nodeinfo:latest
invocationCount:
description: The amount of invocations for the specified function
type: number
format: integer
example: 1337
replicas:
description: The current minimal ammount of replicas
type: number
format: integer
example: 2
availableReplicas:
description: The current available amount of replicas
type: number
format: integer
example: 2
envProcess:
description: Process for watchdog to fork
type: string
example: node main.js
labels:
description: A map of labels for making scheduling or routing decisions
type: object
additionalProperties:
type: string
example:
foo: bar
annotations:
description: A map of annotations for management, orchestration, events and build tasks
type: object
additionalProperties:
type: string
example:
topics: awesome-kafka-topic
foo: bar
required:
- name
- image
- invocationCount
- replicas
- availableReplicas
- envProcess
- labels
Secret:
type: object
properties:
name:
type: string
description: Name of secret
example: aws-key
value:
type: string
description: Value of secret in plain-text
example: changeme
required:
- name
LogEntry:
type: object
properties:
name:
type: string
description: the function name
instance:
type: string
description: the name/id of the specific function instance
timestamp:
type: string
format: date-time
description: the timestamp of when the log message was recorded
text:
type: string
description: raw log message content
SecretName:
type: object
properties:
name:
type: string
description: Name of secret
example: aws-key
externalDocs:
description: More documentation available on Github
url: 'https://github.com/openfaas/faas'