mirror of
https://github.com/openfaas/faas.git
synced 2025-06-08 16:26:47 +00:00
629 lines
17 KiB
YAML
629 lines
17 KiB
YAML
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'
|