Files
fn-serverless/docs/swagger_v2.yml
Reed Allman e13a6fd029 death to format (#1281)
* get rid of old format stuff, utils usage, fix up for fdk2.0 interface

* pure agent format removal, TODO remove format field, fix up all tests

* shitter's clogged

* fix agent tests

* start rolling through server tests

* tests compile, some failures

* remove json / content type detection on invoke/httptrigger, fix up tests

* remove hello, fixup system tests

the fucking status checker test just hangs and it's testing that it doesn't
work so the test passes but the test doesn't pass fuck life it's not worth it

* fix migration

* meh

* make dbhelper shut up about dbhelpers not being used

* move fail status at least into main thread, jfc

* fix status call to have FN_LISTENER

also turns off the stdout/stderr blocking between calls, because it's
impossible to debug without that (without syslog), now that stdout and stderr
go to the same place (either to host stderr or nowhere) and isn't used for
function output this shouldn't be a big fuss really

* remove stdin

* cleanup/remind: fixed bug where watcher would leak if container dies first

* silence system-test logs until fail, fix datastore tests

postgres does weird things with constraints when renaming tables, took the
easy way out

system-tests were loud as fuck and made you download a circleci text file of
the logs, made them only yell when they goof

* fix fdk-go dep for test image. fun

* fix swagger and remove test about format

* update all the gopkg files

* add back FN_FORMAT for fdks that assert things. pfft

* add useful error for functions that exit

this error is really confounding because containers can exit for all manner of
reason, we're just guessing that this is the most likely cause for now, and
this error message should very likely change or be removed from the client
path anyway (context.Canceled wasn't all that useful either, but anyway, I'd
been hunting for this... so found it). added a test to avoid being publicly
shamed for 1 line commits (beware...).
2018-10-26 10:43:04 -07:00

818 lines
23 KiB
YAML

swagger: '2.0'
info:
title: fn
description: The open source serverless platform.
version: "2.0.0"
# the domain of the service
host: "127.0.0.1:8080"
# array of all schemes that your API supports
schemes:
- https
- http
# will be prefixed to all paths
basePath: /v2
consumes:
- application/json
produces:
- application/json
paths:
/apps:
get:
operationId: "ListApps"
summary: "Get A List Of Applications"
description: "Get a filtered list of Applications in alphabetical order."
tags:
- Apps
parameters:
- $ref: '#/parameters/cursor'
- $ref: '#/parameters/perPage'
- name: name
in: query
description: "The Application name to filter by."
required: false
type: string
responses:
200:
description: "A list of Applications."
schema:
$ref: '#/definitions/AppList'
default:
description: "An unexpected error occurred."
schema:
$ref: '#/definitions/Error'
post:
operationId: "CreateApp"
summary: "Create A New Application"
description: "Creates a new Application, returning the complete entity."
tags:
- Apps
parameters:
- name: body
in: body
description: "Application data to insert."
required: true
schema:
$ref: '#/definitions/App'
responses:
200:
description: "Application details and stats."
schema:
$ref: '#/definitions/App'
400:
description: "Parameters are missing or invalid."
schema:
$ref: '#/definitions/Error'
409:
description: "Application with name already exists."
schema:
$ref: '#/definitions/Error'
default:
description: "An unexpected error occurred."
schema:
$ref: '#/definitions/Error'
/apps/{appID}:
delete:
operationId: "DeleteApp"
summary: "Delete An Application"
description: "Delete the specified Application."
tags:
- Apps
parameters:
- $ref: '#/parameters/AppID'
responses:
204:
description: "Application successfully deleted."
404:
description: "Application does not exist."
schema:
$ref: '#/definitions/Error'
default:
description: "An unexpected error occurred."
schema:
$ref: '#/definitions/Error'
get:
operationId: "GetApp"
summary: "Get Information For An Application"
description: "Returns more details about an Application, such as statistics."
tags:
- Apps
parameters:
- $ref: '#/parameters/AppID'
responses:
200:
description: "Application details and stats."
schema:
$ref: '#/definitions/App'
404:
description: "The Application does not exist."
schema:
$ref: '#/definitions/Error'
default:
description: "An unexpected error occurred."
schema:
$ref: '#/definitions/Error'
put:
operationId: "UpdateApp"
summary: "Update an Application"
description: "Updates an Application via merging the provided values."
tags:
- Apps
parameters:
- $ref: '#/parameters/AppID'
- name: body
in: body
description: "Application data to merge with current values."
required: true
schema:
$ref: '#/definitions/App'
responses:
200:
description: "Application details and stats."
schema:
$ref: '#/definitions/App'
400:
description: "Parameters are missing or invalid."
schema:
$ref: '#/definitions/Error'
404:
description: "The Application does not exist."
schema:
$ref: '#/definitions/Error'
default:
description: "An unexpected error occurred."
schema:
$ref: '#/definitions/Error'
/fns:
get:
operationId: "ListFns"
summary: "Get A list Of Functions Within An Application"
description: "Get a filtered list of Functions for an Application, in alphabetical order."
tags:
- Fns
parameters:
- $ref: '#/parameters/AppIDQuery'
- $ref: '#/parameters/cursor'
- $ref: '#/parameters/perPage'
- name: name
in: query
description: "Function name to filter by"
required: false
type: string
responses:
200:
description: "List of Functions."
schema:
$ref: '#/definitions/FnList'
default:
description: "Error"
schema:
$ref: '#/definitions/Error'
post:
operationId: "CreateFn"
summary: "Create A New Function"
description: "Creates a new Function, returning the complete entity."
tags:
- Fns
parameters:
- name: body
in: body
description: "Function data to insert."
required: true
schema:
$ref: '#/definitions/Fn'
responses:
200:
description: "Function details."
schema:
$ref: '#/definitions/Fn'
409:
description: "Function with name already exists."
schema:
$ref: '#/definitions/Error'
400:
description: "Invalid Function."
schema:
$ref: '#/definitions/Error'
default:
description: "An unexpected error occurred."
schema:
$ref: '#/definitions/Error'
/fns/{fnID}:
delete:
operationId: "DeleteFn"
summary: "Delete A Function"
description: "Delete the specified Function."
tags:
- Fns
parameters:
- $ref: '#/parameters/FnID'
responses:
204:
description: "Function successfully deleted."
404:
description: "Function does not exist."
schema:
$ref: '#/definitions/Error'
default:
description: "Error"
schema:
$ref: '#/definitions/Error'
get:
operationId: "GetFn"
summary: "Get Definition Of A Function"
description: "Gets the definition for the Function with the specified ID."
tags:
- Fns
parameters:
- $ref: '#/parameters/FnID'
responses:
200:
description: "Function definition"
schema:
$ref: '#/definitions/Fn'
404:
description: "Function does not exist."
schema:
$ref: '#/definitions/Error'
default:
description: "Error"
schema:
$ref: '#/definitions/Error'
put:
operationId: "UpdateFn"
summary: "Update A Function"
description: "Updates a Function via merging the provided values."
tags:
- Fns
parameters:
- $ref: '#/parameters/FnID'
- name: body
in: body
description: "Function data to merge with current values."
required: true
schema:
$ref: '#/definitions/Fn'
responses:
200:
description: "Updated Function metadata."
schema:
$ref: '#/definitions/Fn'
400:
description: "Parameters are missing or invalid."
schema:
$ref: '#/definitions/Error'
404:
description: "The Function does not exist."
schema:
$ref: '#/definitions/Error'
default:
description: "An unexpected error occurred."
schema:
$ref: '#/definitions/Error'
/triggers:
get:
operationId: "ListTriggers"
summary: "Get A List Of Triggers Within An Application Or Function"
description: "This will list all Triggers for a particular Application or Function, returned in name alphabetical order."
tags:
- Triggers
parameters:
- $ref: '#/parameters/AppIDQuery'
- $ref: '#/parameters/FnIDQuery'
- $ref: '#/parameters/cursor'
- $ref: '#/parameters/perPage'
- name: name
in: query
description: "A Trigger name to filter by."
required: false
type: string
responses:
200:
description: "List of Triggers"
schema:
$ref: '#/definitions/TriggerList'
default:
description: "An unexpected error occurred."
schema:
$ref: '#/definitions/Error'
post:
operationId: "CreateTrigger"
summary: "Create A New Trigger."
description: "Creates a new Trigger, returning the complete entity."
tags:
- Triggers
parameters:
- name: body
in: body
description: "Trigger data to insert."
required: true
schema:
$ref: '#/definitions/Trigger'
responses:
200:
description: "Trigger details."
schema:
$ref: '#/definitions/Trigger'
409:
description: "Trigger with name already exists."
schema:
$ref: '#/definitions/Error'
400:
description: "Invalid Trigger."
schema:
$ref: '#/definitions/Error'
default:
description: "An unexpected error occurred."
schema:
$ref: '#/definitions/Error'
/triggers/{triggerID}:
delete:
operationId: "DeleteTrigger"
summary: "Delete A Trigger"
description: "Delete the specified Trigger."
tags:
- Triggers
parameters:
- $ref: '#/parameters/TriggerID'
responses:
204:
description: "Trigger successfully deleted."
404:
description: "The Trigger does not exist."
schema:
$ref: '#/definitions/Error'
default:
description: "An unexpected error occurred."
schema:
$ref: '#/definitions/Error'
get:
operationId: "GetTrigger"
summary: "Get Definition Of A Trigger"
description: "Gets the definition for the Trigger with the specified ID."
tags:
- Triggers
parameters:
- $ref: '#/parameters/TriggerID'
responses:
200:
description: "Trigger information"
schema:
$ref: '#/definitions/Trigger'
404:
description: "The Trigger does not exist."
schema:
$ref: '#/definitions/Error'
default:
description: "An unexpected error occurred."
schema:
$ref: '#/definitions/Error'
put:
operationId: "UpdateTrigger"
summary: "Update A Trigger"
description: "Updates a Trigger by merging the provided values."
tags:
- Triggers
parameters:
- $ref: '#/parameters/TriggerID'
- name: body
in: body
description: "Trigger data to merge into current value."
required: true
schema:
$ref: '#/definitions/Trigger'
responses:
200:
description: "Updated Triggers metadata."
schema:
$ref: '#/definitions/Trigger'
400:
description: "Parameters are missing or invalid."
schema:
$ref: '#/definitions/Error'
404:
description: "The Trigger does not exist."
schema:
$ref: '#/definitions/Error'
default:
description: "An unexpected error occurred."
schema:
$ref: '#/definitions/Error'
/fns/{fnID}/calls:
get:
summary: Get a fns calls.
description: Get a functions calls, results returned in created_at, descending order (newest first).
tags:
- Call
parameters:
- $ref: '#/parameters/FnID'
- $ref: '#/parameters/cursor'
- $ref: '#/parameters/perPage'
- name: from_time
description: Unix timestamp in seconds, of call.created_at to begin the results at, default 0.
required: false
type: integer
in: query
- name: to_time
description: Unix timestamp in seconds, of call.created_at to end the results at, defaults to latest.
required: false
type: integer
in: query
responses:
200:
description: "List of Calls"
schema:
$ref: '#/definitions/CallList'
404:
description: "Calls not found"
schema:
$ref: '#/definitions/Error'
410:
description: Server does not support this operation.
/fns/{fnID}/calls/{callID}:
get:
summary: Get call information
description: Get call information
tags:
- Call
parameters:
- $ref: '#/parameters/FnID'
- $ref: '#/parameters/CallID'
responses:
200:
description: Call found.
schema:
$ref: '#/definitions/Call'
404:
description: Call not found.
schema:
$ref: '#/definitions/Error'
410:
description: Server does not support this operation.
/fns/{fnID}/calls/{callID}/log:
get:
operationId: "GetCallLogs"
summary: "Get logs for a call."
description: "Get logs for a call."
tags:
- Call
- Log
parameters:
- $ref: '#/parameters/FnID'
- $ref: '#/parameters/CallID'
responses:
200:
description: Log found.
schema:
$ref: '#/definitions/Log'
404:
description: Log not found.
schema:
$ref: '#/definitions/Error'
410:
description: Server does not support this operation.
definitions:
App:
type: object
properties:
id:
type: string
description: "App ID"
readOnly: true
name:
type: string
description: "Name of this app. Must be different than the image name. Can ony contain alphanumeric, -, and _."
readOnly: true
config:
type: object
description: "Application function configuration, applied to all Functions."
additionalProperties:
type: string
annotations:
type: object
description: "Application annotations - this is a map of annotations attached to this app, keys must not exceed 128 bytes and must consist of non-whitespace printable ascii characters, and the seralized representation of individual values must not exeed 512 bytes."
additionalProperties:
type: object
syslog_url:
type: string
description: "A comma separated list of syslog urls to send all function logs to. supports tls, udp or tcp. e.g. tls://logs.papertrailapp.com:1"
created_at:
type: string
format: date-time
description: "Time when app was created. Always in UTC."
readOnly: true
updated_at:
type: string
format: date-time
description: "Most recent time that app was updated. Always in UTC."
readOnly: true
AppList:
type: object
required:
- items
properties:
next_cursor:
type: string
description: "Cursor to send with subsequent request to receive the next page, if non-empty."
readOnly: true
items:
type: array
items:
$ref: '#/definitions/App'
Fn:
type: object
properties:
id:
type: string
description: "Unique identifier"
readOnly: true
name:
type: string
description: "Unique name for this function."
app_id:
type: string
description: "App ID."
image:
type: string
description: "Full container image name, e.g. hub.docker.com/fnproject/yo or fnproject/yo (default registry: hub.docker.com)"
memory:
type: integer
format: uint64
description: "Maximum usable memory given to function (MiB)."
timeout:
type: integer
default: 30
format: int32
description: "Timeout for executions of a function. Value in Seconds."
idle_timeout:
type: integer
default: 30
format: int32
description: "Hot functions idle timeout before container termination. Value in Seconds."
config:
type: object
description: "Function configuration key values."
additionalProperties:
type: string
annotations:
type: object
description: "Func annotations - this is a map of annotations attached to this func, keys must not exceed 128 bytes and must consist of non-whitespace printable ascii characters, and the seralized representation of individual values must not exeed 512 bytes."
additionalProperties:
type: object
created_at:
type: string
format: date-time
description: "Time when function was created. Always in UTC RFC3339."
readOnly: true
updated_at:
type: string
format: date-time
description: "Most recent time that function was updated. Always in UTC RFC3339."
readOnly: true
FnList:
type: object
required:
- items
properties:
next_cursor:
type: string
description: "Cursor to send with subsequent request to receive the next page, if non-empty."
readOnly: true
items:
type: array
items:
$ref: '#/definitions/Fn'
Trigger:
type: object
properties:
id:
type: string
description: "Unique Trigger identifier."
readOnly: true
name:
type: string
description: "Unique name for this trigger, used to identify this trigger."
type:
type: string
description: "Class of trigger, e.g. schedule, http, queue"
source:
type: string
description: "URI path for this trigger. e.g. `sayHello`, `say/hello`"
fn_id:
type: string
description: "Opaque, unique Function identifier"
readOnly: true
app_id:
type: string
description: "Opaque, unique Application identifier"
readOnly: true
annotations:
type: object
description: "Trigger annotations - this is a map of annotations attached to this trigger, keys must not exceed 128 bytes and must consist of non-whitespace printable ascii characters, and the seralized representation of individual values must not exeed 512 bytes."
additionalProperties:
type: object
created_at:
type: string
format: date-time
description: "Time when trigger was created. Always in UTC."
readOnly: true
updated_at:
type: string
format: date-time
description: "Most recent time that trigger was updated. Always in UTC."
readOnly: true
TriggerList:
type: object
required:
- items
properties:
next_cursor:
type: string
description: "Cursor to send with subsequent request to receive the next page, if non-empty."
readOnly: true
items:
type: array
items:
$ref: '#/definitions/Trigger'
Error:
type: object
properties:
message:
type: string
readOnly: true
fields:
type: string
readOnly: true
Log:
type: object
properties:
call_id:
type: string
description: Call UUID ID
log:
type: string # maybe bytes, long logs wouldn't fit into string type
Call:
type: object
properties:
id:
type: string
description: Call ID.
readOnly: true
status:
type: string
description: Call execution status.
readOnly: true
error:
type: string
description: Call execution error, if status is 'error'.
readOnly: true
app_id:
type: string
description: App ID of fn that executed this call.
readOnly: true
fn_id:
type: string
description: Fn ID of fn that executed this call.
readOnly: true
created_at:
type: string
format: date-time
description: Time when call was submitted. Always in UTC.
readOnly: true
started_at:
type: string
format: date-time
description: Time when call started execution. Always in UTC.
readOnly: true
completed_at:
type: string
format: date-time
description: Time when call completed, whether it was successul or failed. Always in UTC.
readOnly: true
stats:
type: array
items:
$ref: '#/definitions/Stat'
description: A histogram of stats for a call, each is a snapshot of a calls state at the timestamp.
readOnly: true
CallList:
type: object
required:
- items
properties:
next_cursor:
type: string
description: "Cursor to send with subsequent request to recieve next page, if non-empty."
readOnly: true
items:
type: array
items:
$ref: '#/definitions/Call'
Stat:
type: object
properties:
timestamp:
type: string
format: date-time
metrics:
type: object
properties:
net_rx:
type: integer
format: int64
net_tx:
type: integer
format: int64
mem_limit:
type: integer
format: int64
mem_usage:
type: integer
format: int64
disk_read:
type: integer
format: int64
disk_write:
type: integer
format: int64
cpu_user:
type: integer
format: int64
cpu_total:
type: integer
format: int64
cpu_kernel:
type: integer
format: int64
parameters:
cursor:
name: cursor
description: "Cursor from previous response.next_cursor to begin results after, if any."
required: false
type: string
in: query
perPage:
name: per_page
description: "Number of results to return, defaults to 30. Max of 100."
required: false
type: integer
in: query
AppID:
name: appID
in: path
description: "Opaque, unique Application ID."
required: true
type: string
FnID:
name: fnID
in: path
description: "Opaque, unique Function ID."
required: true
type: string
TriggerID:
name: triggerID
in: path
description: "Opaque, unique Trigger ID."
required: true
type: string
CallID:
name: callID
in: path
description: "Opaque, unique Call ID."
required: true
type: string
FnIDQuery:
name: fn_id
in: query
description: "Function ID."
required: false
type: string
AppIDQuery:
name: app_id
in: query
description: "Application ID."
required: false
type: string