Dashboard HTTP API#
In this document#
Notes#
metadata.name
is mandatory in all bodies (required to identify the resource).If you omit
namespace
, the dashboard uses the default namespace, as configured in its command line arguments
Function#
Listing all functions#
Request#
URL:
GET /api/functions
Headers:
x-nuclio-function-namespace
: Namespace (required)x-nuclio-project-name
: Filter by project name (optional)
Response#
Status code: 200
Body:
{
"echo": {
"metadata": {
"name": "echo",
"namespace": "nuclio",
"labels": {
"nuclio.io/project-name": "my-project-1"
}
},
"spec": {
"handler": "Handler",
"runtime": "golang",
"resources": {},
"image": "localhost:5000/nuclio/processor-echo:ba5v992vlcq000a2b640",
"httpPort": 30400,
"replicas": 1,
"version": -1,
"alias": "latest",
"build": {
"path": "http://127.0.0.1:8070/sources/echo.go",
"registry": "localhost:5000",
"noBaseImagesPull": true
},
"runRegistry": "localhost:5000"
},
"status": {
"state": "ready"
}
},
"hello-world": {
"metadata": {
"name": "hello-world",
"namespace": "nuclio"
},
"spec": {
"runtime": "golang",
"resources": {},
"image": "localhost:5000/",
"alias": "latest",
"build": {
"path": "https://raw.githubusercontent.com/nuclio/nuclio/master/hack/examples/golang/helloworld/helloworld.go",
"registry": "192.168.64.7:5000",
"noBaseImagesPull": true
},
"runRegistry": "localhost:5000"
},
"status": {
"state": "building"
}
}
}
Getting a function by name#
Request#
URL:
GET /api/functions/<function name>
Headers:
x-nuclio-function-namespace
: Namespace (required)
Response#
Status code: 200
Body:
{
"metadata": {
"name": "echo",
"namespace": "nuclio",
"labels": {
"nuclio.io/project-name": "my-project-1"
}
},
"spec": {
"handler": "Handler",
"runtime": "golang",
"resources": {},
"image": "localhost:5000/nuclio/processor-echo:ba5v992vlcq000a2b640",
"httpPort": 30400,
"replicas": 1,
"version": -1,
"alias": "latest",
"build": {
"path": "http://127.0.0.1:8070/sources/echo.go",
"registry": "localhost:5000",
"noBaseImagesPull": true
},
"runRegistry": "localhost:5000"
},
"status": {
"state": "ready"
}
}
Creating a function#
To create a function, provide the following request and then periodically GET the function until status.state
is set
to ready
or error
. It is guaranteed that by the time the response is returned, getting the function will yield a
body and not 404
.
Request#
URL:
POST /api/functions
Headers:
Content-Type
: Must be set toapplication/json
X-nuclio-creation-state-updated-timeout
: Set the timout for the function creation state to change (optional, defaults to1m
)
Body:
{
"metadata": {
"name": "hello-world",
"namespace": "nuclio",
"labels": {
"nuclio.io/project-name": "function-project"
}
},
"spec": {
"runtime": "golang",
"build": {
"path": "https://raw.githubusercontent.com/nuclio/nuclio/master/hack/examples/golang/helloworld/helloworld.go",
"registry": "192.168.64.7:5000",
"noBaseImagesPull": true
},
"runRegistry": "localhost:5000"
}
}
Response#
Status code: 202
Updating a function#
Updating a function is similar to creating a function. The only differences are:
The method is
PUT
rather thanPOST
You must provide certain fields (e.g.
spec.image
) which should be taken from aGET
- update does not currently support augmentation. Whatever you pass in the body is the new function spec.
Request#
URL:
PUT /api/functions/<function name>
Headers:
Content-Type
: Must be set toapplication/json
X-nuclio-creation-state-updated-timeout
: Set the timout for the function creation state to change (optional, defaults to1m
)
Body:
{
"metadata": {
"name": "hello-world",
"namespace": "nuclio"
},
"spec": {
"handler": "Handler",
"runtime": "golang",
"resources": {},
"image": "localhost:5000/nuclio/processor-hello-world:latest",
"version": -1,
"alias": "latest",
"replicas": 1,
"build": {
"path": "/var/folders/w7/45z_c5lx2n3571nf6hkdvqqw0000gn/T/nuclio-build-238269306/download/helloworld.go",
"registry": "192.168.64.7:5000",
"noBaseImagesPull": true
},
"runRegistry": "localhost:5000"
},
"status": {
"state": "ready"
}
}
Response#
Status code: 202
Patching a function#
Patching a function allows you to change the function’s state.
Currently, the only supported state is ready
, which allows redeploying functions (e.g, after importing functions).
Request#
URL:
PATCH /api/functions/<function name>
Headers:
X-nuclio-wait-function-action
: Set to true to wait for the function to be ready (optional, defaults tofalse
)X-nuclio-function-namespace
: Namespace (required)X-Nuclio-Verify-External-Registry
: Set to true to patch function only if registry is external
Body:
{
"desiredState": "ready"
}
Supported desired states: [ready, scaledToZero]
Response#
Status code: 204
Invoking a function#
Request#
The HTTP method you apply to this endpoint is the one with which dashboard will invoke the function. For example, if
you DELETE /api/function_invocations
, the HTTP method in the event as received by the function will be DELETE
.
URL:
<Method> /api/function_invocations
Headers:
x-nuclio-function-name
: Function name (required)x-nuclio-function-namespace
: Namespace (required)x-nuclio-invoke-url
: Function invocation url to use (required)x-nuclio-path
: The path to invoke the function with (can be empty to invoke with/
)x-nuclio-invoke-timeout
: Function invocation request timeout (e.g.:1s
)x-nuclio-skip-tls-verification
: Skip TLS verification when invoking the function (e.g.:true
)Any other header is passed transparently to the function
Body: Raw body passed as is to the function
Response#
Status code: As returned by the function
Headers:As returned by the function
Body: As returned by the function
Deleting a function#
Request#
URL:
DELETE /api/functions
Headers:
Content-Type
: Must be set toapplication/json
X-nuclio-delete-function-ignore-state-validation
: Whentrue
- allow deleting function in transient mode (e.g.:building
). Otherwise, disallow.
Body:
{
"metadata": {
"name": "hello-world",
"namespace": "nuclio"
}
}
Response#
Status code: 204
Get function replica names#
Request#
URL:
GET /api/functions/<function name>/replicas
Headers:
x-nuclio-function-namespace
: Namespace (required)
Response#
Status code: 200
Body:
{
"names": [
"nuclio-nuclio-somefunction"
]
}
Get function replica logs stream#
Request#
URL:
GET /api/functions/<function name>/logs/<replica-name>
Headers:
x-nuclio-function-namespace
: Namespace (required)
Params
follow
: Follow the replica log stream (default: true)since
: A relative time before the current time from which to show logs (optional, e.g.:1h
)tailLines
: Number of lines to show from the end of the logs (optional, e.g.:100
)containerName
: Container name to show logs from. If not supplied the function container logs will be retrieved [only relevant inkube
platform] (optional, e.g.:sidecar-container
)
Response#
Status code: 200
Body:
...Function replica logs...
Project#
Listing all projects#
Request#
URL:
GET /api/projects
Headers:
x-nuclio-project-namespace
: Namespace (optional)
Response#
Status code: 200
Body:
{
"my-project-1": {
"metadata": {
"name": "my-project-1",
"namespace": "nuclio"
},
"spec": {
"description": "Some description"
}
},
"my-project-2": {
"metadata": {
"name": "my-project-2",
"namespace": "nuclio"
},
"spec": {
"description": "Some description"
}
}
}
Getting a project by name#
Request#
URL:
GET /api/projects/<project name>
Headers:
x-nuclio-project-namespace
: Namespace (optional)
Response#
Status code: 200
Body:
{
"metadata": {
"name": "my-project-1",
"namespace": "nuclio"
},
"spec": {
"description": "Some description"
}
}
Creating a project#
Creating a project is synchronous. By the time the response returns, the project has been created. If name is omitted, a UUID is generated.
Request#
URL:
POST /api/projects
Headers:
Content-Type
: Must be set toapplication/json
Body:
{
"metadata": {
"name": "my-project-1",
"namespace": "nuclio"
},
"spec": {
"description": "Some description"
}
}
Response#
Status code: 201
Updating a project by name#
Request#
URL:
PUT /api/projects/<project-name>
Headers:
Content-Type
: Must be set toapplication/json
Body:
{
"metadata": {
"name": "my-project-1",
"namespace": "nuclio"
},
"spec": {
"description": "Some description"
}
}
Response#
Status code: 204
Deleting a project#
Only projects with no functions can be deleted. Attempting to delete a project with functions will result in an error being returned.
Request#
URL:
DELETE /api/projects
Headers:
Content-Type
: Must be set toapplication/json
Body:
{
"metadata": {
"name": "my-project-1",
"namespace": "nuclio"
}
}
Response#
Status code: 204
Function event#
A function event allows users to store reusable events with which to test their functions, rather than invoking a
function with ad-hoc data. A function event is bound to a function through the nuclio.io/function-name
label providing
a 1:N relationship between a function and function events.
Trigger attributes#
The function event contains per-trigger attributes. The triggerKind
specifies which kind of trigger the function event
should invoke through.
HTTP trigger (http
)#
method
(string): Any standard HTTP method (e.g.GET
,POST
, etc)path
(string, optional): The path to invoke, defaulting to/
(e.g./my/invoke/path
)headers
(map, optional): A map of headers
Listing all function events#
Request#
URL:
GET /api/function_events
Headers:
x-nuclio-function-event-namespace
: Namespace (required)x-nuclio-function-name
: Function name (optional)
Response#
Status code: 200
Body:
{
"bb016570-348d-4ea8-8092-799ae8f27845": {
"metadata": {
"name": "bb016570-348d-4ea8-8092-799ae8f27845",
"namespace": "nuclio",
"labels": {
"nuclio.io/function-name": "my-function"
}
},
"spec": {
"displayName": "My function event",
"body": "some body",
"triggerKind": "http",
"attributes": {
"headers": {
"x-header-1": "a",
"x-header-2": 1
},
"method": "GET",
"path": "/some/path"
}
}
},
"named-fe1": {
"metadata": {
"name": "named-fe1",
"namespace": "nuclio",
"labels": {
"nuclio.io/function-name": "my-function"
}
},
"spec": {
"displayName": "My named function event",
"body": "a body",
"triggerKind": "http",
"attributes": {
"headers": {
"x-header-1": "a",
"x-header-2": 1
},
"method": "GET",
"path": "/some/path"
}
}
}
}
Getting a function event by name#
Request#
URL:
GET /api/function_events/<function event name>
Headers:
x-nuclio-function-event-namespace
: Namespace (required)
Response#
Status code: 200
Body:
{
"metadata": {
"name": "named-fe1",
"namespace": "nuclio",
"labels": {
"nuclio.io/function-name": "my-function"
}
},
"spec": {
"displayName": "My named function event",
"body": "a body",
"triggerKind": "http",
"attributes": {
"headers": {
"x-header-1": "a",
"x-header-2": 1
},
"method": "GET",
"path": "/some/path"
}
}
}
Creating a function event#
Creating a function event is synchronous. By the time the response returns, the function event has been created.
If name
is omitted, a UUID is generated. Set the function name via the nuclio.io/function-name
label
in metadata.labels
.
Request#
URL:
POST /api/function_events
Headers:
Content-Type
: Must be set toapplication/json
Body:
{
"metadata": {
"namespace": "nuclio",
"labels": {
"nuclio.io/function-name": "my-function"
}
},
"spec": {
"displayName": "My function event",
"body": "some body",
"attributes": {
"headers": {
"x-header-1": "a",
"x-header-2": 1
},
"method": "GET",
"path": "/some/path"
}
}
}
Response#
Status code: 201
Body:
{
"metadata": {
"name": "db11d276-4c6a-4200-b096-d9b8fe2031cd",
"namespace": "nuclio",
"labels": {
"nuclio.io/function-name": "my-function"
}
},
"spec": {
"displayName": "My function event",
"body": "some body",
"triggerKind": "http",
"attributes": {
"headers": {
"x-header-1": "a",
"x-header-2": 1
},
"method": "GET",
"path": "/some/path"
}
}
}
Updating a function event#
Request#
URL:
PUT /api/function_events
Headers:
Content-Type
: Must be set toapplication/json
Body:
{
"metadata": {
"name": "named-fe1",
"namespace": "nuclio",
"labels": {
"nuclio.io/function-name": "my-function"
}
},
"spec": {
"displayName": "My updated named function event",
"body": "a body",
"triggerKind": "http",
"attributes": {
"headers": {
"x-header-1": "a",
"x-header-2": 1
},
"method": "GET",
"path": "/some/path"
}
}
}
Response#
Status code: 204
Deleting a function event#
Request#
URL:
DELETE /api/function_events
Headers:
Content-Type
: Must be set toapplication/json
Body:
{
"metadata": {
"name": "named-fe1",
"namespace": "nuclio"
}
}
Response#
Status code: 204
Function template#
Listing all function templates#
Request#
URL:
GET /api/function_templates
Headers:
x-nuclio-filter-contains
: Substring that appears either in name or configuration of the function (optional)
Response#
Status code: 200
Body:
{
"dates:878fefcf-a5ef-4c9b-8099-09d6c57cb426": {
"metadata": {
"name": "dates:878fefcf-a5ef-4c9b-8099-09d6c57cb426"
},
"spec": {
"description": "Uses moment.js (which is installed as part of the build) to add a specified amount of time to \"now\", and returns this amount as a string.\n",
"handler": "handler",
"runtime": "nodejs",
"resources": {},
"build": {
"functionSourceCode": "<base64 encoded string>",
"commands": [
"npm install --global moment"
]
}
}
},
"encrypt:1ce3c946-056a-4ea2-99f2-fa8491d8647c": {
"metadata": {
"name": "encrypt:1ce3c946-056a-4ea2-99f2-fa8491d8647c"
},
"spec": {
"description": "Uses a third-party Python package to encrypt the event body, and showcases build commands for installing both OS-level and Python packages.\n",
"handler": "encrypt:encrypt",
"runtime": "python",
"resources": {},
"build": {
"functionSourceCode": "<base64 encoded string>",
"commands": [
"apk update",
"apk add --no-cache gcc g++ make libffi-dev openssl-dev",
"pip install simple-crypt"
]
}
}
}
}
API Gateways#
Listing all API gateways#
Request#
URL:
GET /api/api_gateways
Headers:
x-nuclio-api-gateway-namespace
: Namespace (required)x-nuclio-project-name
: Filter by project name (optional)
Response#
Status code: 200
Body:
{
"agw": {
"metadata": {
"name": "agw",
"namespace": "nuclio",
"labels": {
"nuclio.io/project-name": "my-project-1"
}
},
"spec": {
"host": "<api-gateway-endpoint>",
"name": "agw",
"path": "/",
"authenticationMode": "none",
"upstreams": [
{
"kind": "nucliofunction",
"nucliofunction": {
"name": "mu-func-1"
}
}
]
},
"status": {
"name": "agw",
"state": "ready"
}
},
"another-gateway": {
"metadata": {
"name": "another-gateway",
"namespace": "nuclio",
"labels": {
"nuclio.io/project-name": "my-project-1"
}
},
"spec": {
"host": "<api-gateway-endpoint>",
"name": "another-gateway",
"path": "/",
"authenticationMode": "accessKey",
"upstreams": [
{
"kind": "nucliofunction",
"nucliofunction": {
"name": "my-func-2"
}
}
]
},
"status": {
"name": "another-gateway",
"state": "ready"
}
}
}
Getting an API gateway by name#
Request#
URL:
GET /api/api_gateways/<api-gateway-name>
Headers:
x-nuclio-api-gateway-namespace
: Namespace (required)
Response#
Status code: 200
Body:
{
"metadata": {
"name": "agw",
"namespace": "nuclio",
"labels": {
"nuclio.io/project-name": "my-project-1"
}
},
"spec": {
"name": "agw",
"host": "<api-gateway-endpoint>",
"path": "/",
"authenticationMode": "none",
"upstreams": [
{
"kind": "nucliofunction",
"nucliofunction": {
"name": "my-func-1"
}
}
]
},
"status": {
"name": "agw",
"state": "ready"
}
}
Creating an API gateway#
To create an API gateway, provide the following request and then periodically GET the api gateway until status.state
is set
to ready
or error
. It is guaranteed that by the time the response is returned, getting the api gateway will yield a
body and not 404
.
Request#
URL:
POST /api/api_gateways
Headers:
Content-Type
: Must be set toapplication/json
Body:
{
"metadata":{
"name":"agw",
"labels":{
"nuclio.io/project-name":"my-project-1"
}
},
"spec":{
"name":"agw",
"host": "<api-gateway-endpoint>",
"description":"",
"path":"",
"authenticationMode":"none",
"upstreams":[
{
"kind":"nucliofunction",
"nucliofunction":{
"name":"my-func-1"
},
"percentage":0
}
]
}
}
Response#
Status code: 202
Updating an API gateway#
Updating an API gateway is similar to creating an API gateway. The only differences are:
The method is
PUT
rather thanPOST
You must provide certain fields to change, such as
spec.description
,spec.path
andspec.authenticationMode
.
Request#
URL:
PUT /api/api_gateways/<api-gateway-name>
Headers:
Content-Type
: Must be set toapplication/json
Body:
{
"metadata": {
"name": "agw",
"namespace": "nuclio",
"labels": {
"nuclio.io/project-name": "my-project-1"
}
},
"spec": {
"name": "agw",
"host": "<api-gateway-endpoint>",
"path": "new-agw-path",
"authenticationMode": "basic",
"upstreams": [
{
"kind": "nucliofunction",
"nucliofunction": {
"name": "my-func-1"
}
}
],
"description": "new description"
},
"status": {
"name": "agw",
"state": "ready"
}
}
Response#
Status code: 204
Invoking an API gateway#
Request#
Invoking an API gateway is done by calling endpoint that is given in the api geteway’s spec.host
field.
URL:
<Method> <api-gateway-endpoint>
Headers:
Any header is passed transparently to the function
Body: Raw body passed as is to the function
Response#
Status code: As returned by the function
Headers:As returned by the function
Body: As returned by the function
Deleting an API gateway#
Request#
URL:
DELETE /api/api_gateways
Headers:
Content-Type
: Must be set toapplication/json
Body:
{
"metadata":{
"name":"<api-gateway-name>"
}
}
Response#
Status code: 204
V3IO Streams#
A V3IO stream can be configured as a function trigger. More information can be found in v3ioStream: Iguazio Data Science Platform Stream Trigger.
Listing all v3io streams in a project#
Request#
URL:
GET /api/v3io_streams
Headers:
x-nuclio-project-name
: projectName (required)
Response#
Status code: 200
Body: for each stream in the project:
{
"function-name@stream-name": {
"consumerGroup": "<consumer-group>",
"containerName": "<container-name>",
"streamPath": "/path/of/stream"
}
}
Get v3io stream shard lags#
Request#
URL:
POST /api/v3io_streams/get_shard_lags
Headers:
x-nuclio-project-name
: projectName (required)
Body: include stream information
{
"consumerGroup": "<consumer-group>",
"containerName": "<container-name>",
"streamPath": "/path/to/stream"
}
Response#
Status code: 200
Body: for every consumer group, a map with the shard ID as the key, and shard lag details as values, for all shards.
{
"<container-name>/<stream-path>": {
"<consumer-group>": {
"shard-id-0": {
"committed": "<committed-sequences-number>",
"current": "<current-sequence-number>",
"lag": "<shard-lag>"
},
...
"shard-id-N": {
"committed": "<committed-sequences-number>",
"current": "<current-sequence-number>",
"lag": "<shard-lag>"
}
}
}
}
Misc#
Getting version#
Request#
URL:
GET /api/versions
Response#
Status code: 200
Body:
{
"dashboard": {
"arch": "amd64",
"gitCommit": "<some commit hash>",
"label": "latest",
"os": "darwin"
}
}
Getting external IP addresses#
The user must know through which URL a function can be invoked in case load balancing / ingresses are not used. If the user concatenates one of the external IP addresses returned by this endpoint with the function’s HTTP port, as specified in its spec/status - this will form a valid invocation URL.
Request#
URL:
GET /api/external_ip_addresses
Response#
Status code: 200
Body:
{
"externalIPAddresses": {
"addresses": [
""
]
}
}