Skip to main content

Coordination API (1.0.0)

Download OpenAPI specification:Download

Seaplane IO, Inc.: support@seaplane.io License: Apache 2.0

Seaplane Global Coordination API

config

Metadata key-value store API

Get contents of root directory

Authorizations:
BasicAuth
query Parameters
from
string
Example: from=base64:dGhlIG5leHQga2V5

The range queries return one page of results, if a GET / query returns a KeyValueRange with a non-null next_key you can repeat this query with the from parameter set to the next_key value from the previous query to see the next page of results. Values of the from parameter should be prefixed with the string "base64:"

Responses

Response samples

Content type
application/json
{
  • "next_key": "dGhlIG5leHQga2V5",
  • "kvs": [
    ]
}

Get a key-value pair

Authorizations:
BasicAuth
path Parameters
key
required
string
Example: Zm9vL2Jhcgo

Key of the key-value pair, the value should encoded using Base 64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

Responses

Response samples

Content type
application/json
{
  • "key": "key_foo",
  • "value": "something"
}

Set a key-value pair

Authorizations:
BasicAuth
path Parameters
key
required
string
Example: Zm9vL2Jhcgo

Key of the key-value pair, the value should encoded using Base 64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

Request Body schema: application/octet-stream

Base64-encoded value of the key-value pair

string

Responses

Response samples

Content type
application/json
"OK"

Delete a key-value pair

Authorizations:
BasicAuth
path Parameters
key
required
string
Example: Zm9vL2Jhcgo

Key of the key-value pair, the value should encoded using Base 64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

Responses

Response samples

Content type
application/json
"OK"

List the contents of a directory

Authorizations:
BasicAuth
path Parameters
key
required
string
Example: Zm9vL2Jhcgo

Key pointing to a directory, the value should encoded using Base 64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

query Parameters
from
string
Example: from=base64:dGhlIG5leHQga2V5

The range queries return one page of results, if a GET / query returns a KeyValueRange with a non-null next_key you can repeat this query with the from parameter set to the next_key value from the previous query to see the next page of results. Values of the from parameter should be prefixed with the string "base64:"

Responses

Response samples

Content type
application/json
{
  • "next_key": "dGhlIG5leHQga2V5",
  • "kvs": [
    ]
}

locks

Locks API

Get all locks in the root directory

Authorizations:
BasicAuth
query Parameters
from
string
Example: from=base64:bG9tb25k

Listing a directory of locks returns one page of results, if a GET / query returns a LockRange with a non-null next_lock you can repeat this query with the from parameter set to the next_lock value from the previous query to see the next page of results. Values of the from parameter should be prefixed with the string "base64:"

Responses

Response samples

Content type
application/json
{
  • "next_lock": "bG9tb25k",
  • "locks": [
    ]
}

Get locks in a given directory

Authorizations:
BasicAuth
path Parameters
dir
required
string (LockName)
Example: bG9tb25k

Name of a directory containing locks, the value should encoded using Base 64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

query Parameters
from
string
Example: from=base64:bG9tb25k

Listing a directory of locks returns one page of results, if a GET / query returns a LockRange with a non-null next_lock you can repeat this query with the from parameter set to the next_lock value from the previous query to see the next page of results. Values of the from parameter should be prefixed with the string "base64:"

Responses

Response samples

Content type
application/json
{
  • "next_lock": "bG9tb25k",
  • "locks": [
    ]
}

Get the information around a currently held lock

Authorizations:
BasicAuth
path Parameters
name
required
string (LockName)
Example: bG9tb25k

Name of the lock, the value should encoded using Base 64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

Responses

Response samples

Content type
application/json
{
  • "name": "bG9tb25k",
  • "id": "AOEHFRa4Ayg",
  • "info": {
    }
}

Attempt to acquire a lock

Authorizations:
BasicAuth
path Parameters
name
required
string (LockName)
Example: bG9tb25k

Name of the lock, the value should encoded using Base 64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

query Parameters
ttl
required
integer (TTL) [ 1 .. 4095 ]
Example: ttl=3600

The TTL set on the lock when it was last acquired/renewed in seconds

client-id
required
string (ClientID)
Example: client-id=worker-321

The Client ID of the current lock holder.

Responses

Response samples

Content type
application/json
{
  • "id": "AOEHFRa4Ayg",
  • "sequencer": 3
}

Release a currently held lock

Authorizations:
BasicAuth
path Parameters
name
required
string (LockName)
Example: bG9tb25k

Name of the lock, the value should encoded using Base 64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

query Parameters
id
required
string (LockID)
Example: id=AOEHFRa4Ayg

ID which allows for the renewal/release of a lock, represents "holding" the lock, this is usually only seen by the original acquirer of the lock but may be leaked by listing the locks. (NOTE: This allows you to alter lock semantics drastically so please ensure you understand the consequences before use)

Responses

Response samples

Content type
application/json
"OK"

Renew a held lock, with a given TTL

Authorizations:
BasicAuth
path Parameters
name
required
string (LockName)
Example: bG9tb25k

Name of the lock, the value should encoded using Base 64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

query Parameters
id
required
string (LockID)
Example: id=AOEHFRa4Ayg

ID which allows for the renewal/release of a lock, represents "holding" the lock, this is usually only seen by the original acquirer of the lock but may be leaked by listing the locks. (NOTE: This allows you to alter lock semantics drastically so please ensure you understand the consequences before use)

ttl
required
integer (TTL) [ 1 .. 4095 ]
Example: ttl=3600

The TTL set on the lock when it was last acquired/renewed in seconds

Responses

Response samples

Content type
application/json
"OK"

restrict

Provider and region restrictions API

List information about all provider and region restrictions

Authorizations:
BasicAuth
query Parameters
from
string
Example: from=base64:dGhlIG5leHQga2V5

The range queries return one page of results, if a GET / query returns a KeyValueRange with a non-null next_key you can repeat this query with the from parameter set to the next_key value from the previous query to see the next page of results. Values of the from parameter should be prefixed with the string "base64:"

Responses

Response samples

Content type
application/json
{
  • "next_api": "locks",
  • "next_key": "dGhlIG5leHQga2V5",
  • "restrictions": [
    ]
}

List information about the provider and region restrictions for an API

Authorizations:
BasicAuth
path Parameters
api
required
string (RestrictionApi)
Enum: "config" "locks"
Example: config

The name of a metadata API, for example "config" or "locks"

query Parameters
from
string
Example: from=base64:dGhlIG5leHQga2V5

The range queries return one page of results, if a GET / query returns a KeyValueRange with a non-null next_key you can repeat this query with the from parameter set to the next_key value from the previous query to see the next page of results. Values of the from parameter should be prefixed with the string "base64:"

Responses

Response samples

Content type
application/json
{
  • "next_key": "dGhlIG5leHQga2V5",
  • "restrictions": [
    ]
}

Replace all geographical or provider restrictions on a given directory with new restrictions

Authorizations:
BasicAuth
path Parameters
api
required
string (RestrictionApi)
Enum: "config" "locks"
Example: config

The name of a metadata API, for example "config" or "locks"

key
required
string
Example: Zm9vL2Jhcgo

Key pointing to a directory, the value should encoded using Base 64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

Request Body schema: application/json

JSON object containing explicit allow or deny lists for geographies and cloud providers to be associated with a given directory

regions_allowed
Array of strings or null (Region)
Enum: "XA" "XC" "XE" "XF" "XN" "XO" "XQ" "XS" "XU"

A list of region codes

regions_denied
Array of strings or null (Region)
Enum: "XA" "XC" "XE" "XF" "XN" "XO" "XQ" "XS" "XU"

A list of region codes

providers_allowed
Array of strings or null (Provider)
Enum: "AWS" "Azure" "DigitalOcean" "Equinix" "GCP"

A list of provider names

providers_denied
Array of strings or null (Provider)
Enum: "AWS" "Azure" "DigitalOcean" "Equinix" "GCP"

A list of provider names

Responses

Request samples

Content type
application/json
{
  • "providers_allowed": [
    ],
  • "providers_denied": [
    ],
  • "regions_allowed": [
    ],
  • "regions_denied": [
    ]
}

Response samples

Content type
application/json
"OK"

Get information about the provider and region restrictions for a specific directory

Authorizations:
BasicAuth
path Parameters
api
required
string (RestrictionApi)
Enum: "config" "locks"
Example: config

The name of a metadata API, for example "config" or "locks"

key
required
string
Example: Zm9vL2Jhcgo

Key pointing to a directory, the value should encoded using Base 64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

Responses

Response samples

Content type
application/json
{
  • "api": "config",
  • "directory": "Zm9vL2Jhcgo",
  • "details": {
    },
  • "state": "enforced"
}

Remove restrictions on a directory

Authorizations:
BasicAuth
path Parameters
api
required
string (RestrictionApi)
Enum: "config" "locks"
Example: config

The name of a metadata API, for example "config" or "locks"

key
required
string
Example: Zm9vL2Jhcgo

Key pointing to a directory, the value should encoded using Base 64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

Responses

Response samples

Content type
application/json
"OK"