Apcera REST API Reference

This reference describes the API endpoints and model types in the Apcera REST API.

GET /apc/download/{platform}

Downloads the APC command-line utility for the specified platform.

MIME Types

Request
Accept: application/x-gzip,application/zip
Response
Content-Type: application/x-gzip,application/zip

Request Parameters

Name Description Location Data Type Notes
platform

Target platform. Can be one of the following values:

  • linux
  • osx
  • linux_amd64
  • osx_amd64
  • darwin_amd64
  • darwin
Path String , valid values:
  • "linux_amd64"
  • "linux"
  • "osx_amd64"
  • "darwin_amd64"
  • "darwin"
  • "osx"
Required

Response

200 OK

A successful response contains the APC binary for the specified platform.

GET /audit

Returns a list AuditLogItem objects. You can optionally filter the returned list by start time, end time, FQN, or event type. You can page through a query's result set by combining the offset and limit parameters in the request. For convenience, HTTP headers (Prev and Next) are included in the response that provide the API endpoints to retrieve the previous and next set of query results, respectively.

MIME Types

Request
Accept: application/vnd.apcera.audit;version=1
Response
Content-Type: application/vnd.apcera.audit;version=1

Request Parameters

Name Description Location Data Type Notes
end_time

UNIX timestamp. If specified, only events that occurred on or before the specified time are returned in the response.

Query Number (float)
event_type

If specified, only events of the specified type are returned in the response.

Query String
fqn

If specified, only events on the resource specified by fqn are returned in the response. You can also specify an FQN segment, which may include wildcards for the resource type. For example:

  • *::/ returns all audit logs for all resource types.
  • job::/ returns all audit logs for Job resource types.
  • job::/apcera returns all audit logs for Job resource types in the /apcera namespace and its sub-namespaces.
  • *::/apcera returns all audit logs for all resource types in the /apcera namespace its sub-namespaces.
Query String
limit

Limits the number of records included in the response.

Query Integer
Maximum:
1000
Default:
200
offset

Offset of first record to return in response.

Query Integer
Default:
0
reverse

If present in the query string, reverses the default ordering of query results from most recent first to least recent first.

Query Integer
start_time

UNIX timestamp. If specified, only events that occurred on or after the specified time are returned in the response.

Query Number (float)

Response

200 OK

A successful response is an array of AuditLogItem objects.

Response Headers

Name Description Type
Prev

API endpoint to retrieve the previous set of query results.

string

Next

API endpoint to retrieve the next set of query results.

string

Response example
[
{
"audit_payload": {
"patches": [
{
"oldvalue": "2017-03-27T23:47:37.164719871Z",
"op": "replace",
"path": "job/updated_at",
"value": "2017-03-27T23:47:51.530809553Z"
},
{
"oldvalue": 1,
"op": "replace",
"path": "job/version_id",
"value": 2
}
]
},
"event_type": "job.update",
"event_type_int": 2,
"fqn": "job::/sandbox/admin::api-docs",
"localname": "api-docs",
"namespace": "/sandbox/admin",
"on_behalf_of": "admin@apcera.com",
"principal_name": "api_server@apcera.me",
"resource_type": "job",
"timestamp": 1490658471,
"uuid": "ca47e5a0-1347-11e7-9dd5-06b7728d575f"
},
{
"audit_payload": {
},
"event_type": "job.start",
"event_type_int": 8,
"fqn": "job::/sandbox/admin::api-docs",
"localname": "api-docs",
"namespace": "/sandbox/admin",
"on_behalf_of": "admin@apcera.com",
"principal_name": "api_server@apcera.me",
"resource_type": "job",
"timestamp": 1490658471,
"uuid": "ca47dfb9-1347-11e7-9dd4-06b7728d575f"
}
]

GET /audit/events

Returns a list of the names of all audit event types.

MIME Types

Request
Accept: application/vnd.apcera.auditlogtype;version=1
Response
Content-Type: application/vnd.apcera.auditlogtype;version=1

Request Parameters

None.

Response

200 OK

A successful response is a list of audit event types.

Response example
[
"stagpipe.create",
"network.create",
"subnetpool.create",
"job.removelink",
"job.packageretire",
"route.create",
"job.addbinding",
"service.update",
"network.leave",
"pkg.update",
"service.bind",
"cluster.update",
"stagpipe.update",
"job.packagedeny",
"policy.delete",
"policy.access.denied",
"service.create",
"network.join",
"policy.add",
"policy.update",
"pkg.get",
"secret.install",
"stagpipe.delete",
"drain.add",
"route.update",
"pkg.create",
"service.delete",
"auth.issue",
"job.removebinding",
"job.instancestop",
"job.instancesnapshot",
"job.delete",
"job.connect",
"network.delete",
"job.packageallow",
"job.packagelock",
"policy.access.allowed",
"gateway.promote",
"job.stop",
"job.addroute",
"route.map",
"sempiperule.create",
"secret.create",
"secret.uninstall",
"job.update",
"job.removeroute",
"route.delete",
"provider.create",
"provider.delete",
"job.packageunlock",
"service.unbind",
"auth.allow",
"job.start",
"drain.delete",
"subnetpool.delete",
"auth.deny",
"gateway.demote",
"secret.delete",
"job.create",
"job.packagesetdefault",
"pkg.delete",
"network.show",
"job.addlink",
"quota.update",
"sempiperule.delete"
]

POST /bindings

Creates a new binding between a job and a service, or between two jobs (a job link).

MIME Types

Request
Accept: application/vnd.apcera.binding;version=1
Content-Type: application/vnd.apcera.binding;version=1
Response
Content-Type: application/vnd.apcera.binding;version=1

Request Parameters

None.

Request body

Binding object with required properties.

Response

200 OK

A successful response contains the newly created Binding object.

Response example
{
"env_var": [
"LINKNAME_URI"
],
"fqn": "binding::/::4fe92aad-4ce4-406d-9182-bec4108449a4",
"name": "linkname",
"target_job_fqn": "job::/sandbox/admin::my-service"
}

GET /cluster/admin

Returns an AdminInfo object that contains the cluster administrator's name and email.

MIME Types

Request
Accept: application/vnd.apcera.admin;version=1
Response
Content-Type: application/vnd.apcera.admin;version=1

Request Parameters

None.

Response

200 OK

Successful response.

Response example
{
"email": "jsmith@example.com",
"name": "John Smith"
}

GET /info

Returns a Info object.

MIME Types

Request
Accept: application/vnd.apcera.info;version=1
Response
Content-Type: application/vnd.apcera.info;version=1

Request Parameters

None.

Response

200 OK

Successful response.

Response example
{
"cluster_domain": "apcera.me",
"name": "continuum",
"url": "http://api.example.com/"
}

GET /instance_managers

Returns a list of InstanceManagerStatus objects that provide status and resource usage information for the cluster's instance managers.

MIME Types

Request
Accept: application/vnd.apcera.imstatus;version=1
Response
Content-Type: application/vnd.apcera.imstatus;version=1

Request Parameters

None.

Response

200 OK

Successful response.

Response example
[
{
"ResourcesProvisioned": {
"cpu": 0,
"disk": 12884901888,
"memory": 3632267264,
"netmax": 0,
"network": 70000000
},
"ResourcesTotal": {
"cpu": 2000000,
"disk": 220098199552,
"memory": 17706852352,
"netmax": 0,
"network": 1000000000
},
"datacenter": "us-west-2a",
"hostname": "example-037ffac0",
"num_instances": 10,
"start_time": "2017-03-29T09:04:34.911660001Z",
"system_tags": [
"job-78190a46-170c-4615-82b0-c0065d86a165",
"job-cf4fcf31-1991-4f0e-92eb-24e3f73810ac",
"job-66bc29a1-cbd6-4513-8350-57762d830236",
"job-256b2a1b-c9dd-4ee7-9177-3be4a6a31a89",
"job-5d10f19c-cc38-4020-9a3e-8908561a9664"
],
"tags": [
"aws",
"10.0.0.90",
"037ffac0",
"IM3",
"us-west-2a"
],
"uptime": 136973963250759,
"uuid": "bb1042d5-40f1-4fa2-9b1b-666f8f90ce67"
},
{
"ResourcesProvisioned": {
"cpu": 0,
"disk": 8053063680,
"memory": 3816816640,
"netmax": 0,
"network": 35000000
},
"ResourcesTotal": {
"cpu": 2000000,
"disk": 220098199552,
"memory": 17706852352,
"netmax": 0,
"network": 1000000000
},
"datacenter": "us-west-2c",
"hostname": "example-2f5536c3",
"num_instances": 5,
"start_time": "2017-03-20T23:59:01.635081158Z",
"system_tags": [
"job-28778fe8-a40f-422f-8102-c802c13c2a54",
"job-256b2a1b-c9dd-4ee7-9177-3be4a6a31a89",
"job-47920f21-6c79-41cf-8d88-7ff3b6962cb8"
],
"tags": [
"us-west-2c",
"IM7",
"aws",
"2f5536c3",
"10.0.2.178"
],
"uptime": 860907238329354,
"uuid": "07d40ac2-5087-4dee-b591-b47750a81a03"
}
]

GET /instance_managers/{uuid}

Returns an InstanceManagerStatus provide status and resource information for the specified instance manager.

MIME Types

Request
Accept: application/vnd.apcera.imstatus;version=1
Response
Content-Type: application/vnd.apcera.imstatus;version=1

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the instance manager to retrieve details for.

Path String
Required

Response

200 OK

Successful response.

Response example
{
"ResourcesProvisioned": {
"cpu": 0,
"disk": 8053063680,
"memory": 3816816640,
"netmax": 0,
"network": 35000000
},
"ResourcesTotal": {
"cpu": 2000000,
"disk": 220098199552,
"memory": 17706852352,
"netmax": 0,
"network": 1000000000
},
"datacenter": "us-west-2c",
"hostname": "example-2f5536c3",
"num_instances": 5,
"start_time": "2017-03-20T23:59:01.635081158Z",
"system_tags": [
"job-aac2ce41-85c1-44fd-9c10-32af1ddb03bc",
"job-3e4cd884-4787-4ad2-94f8-16158502e2d6",
"job-e687a0e3-49c8-49e9-9f69-0bea5644b35a",
"job-28778fe8-a40f-422f-8102-c802c13c2a54",
"job-256b2a1b-c9dd-4ee7-9177-3be4a6a31a89",
"job-47920f21-6c79-41cf-8d88-7ff3b6962cb8",
"job-fe043873-0364-455e-923c-bba7ed2b0333"
],
"tags": [
"10.0.2.178",
"us-west-2c",
"IM7",
"aws",
"2f5536c3"
],
"uptime": 924524034923448,
"uuid": "07d40ac2-5087-4dee-b591-b47750a81a03"
}

GET /instance_managers/{uuid}/instances

Returns a list of InstanceStatus objects representing the stastus of all instances being managed by the specified instance manager.

MIME Types

Request
Accept: application/vnd.apcera.instancestatus;version=1
Response
Content-Type: application/vnd.apcera.instancestatus;version=1

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the instance manager whose instances should be retrieved.

Path String
Required

Response

200 OK

Successful response is a list of Instance objects.

Response example
[
{
"job_fqn": "job::/demo::jenkins-master",
"job_uuid": "3e4cd884-4787-4ad2-94f8-16158502e2d6",
"resources": {
"cpu": 0,
"disk": 5368709120,
"memory": 3221225472,
"netmax": 0,
"network": 5000000
},
"start_time": "2017-03-13T17:37:59.989818697Z",
"state": "NEW",
"uptime": 1556882136702122,
"uuid": "a1f6c034-fc4e-45ae-8218-4af2d869fff9"
},
{
"job_fqn": "job::/demo::jenkins-master/http/e687a0e3",
"job_uuid": "e687a0e3-49c8-49e9-9f69-0bea5644b35a",
"resources": {
"cpu": 0,
"disk": 268435456,
"memory": 50331648,
"netmax": 0,
"network": 10000000
},
"start_time": "2017-03-13T17:38:00.158861942Z",
"state": "NEW",
"uptime": 1556881967884253,
"uuid": "863914a3-9374-4511-8936-0e02d8ff6dfd"
}
]

GET /jobs

Returns a list of jobs the current user has permission to read, optionally filtered by query parameters.

MIME Types

Request
Accept: application/vnd.apcera.jobs;version=1
Response
Content-Type: application/vnd.apcera.jobs;version=1

Request Parameters

Name Description Location Data Type Notes
BindingFQN

A Binding FQN (binding::/::19f4d072-7850-4722-8fdf-559e069b7e28, e.g.). Only jobs with the specified binding are returned.

Query String
count

Number of jobs to return in the response. By default, all jobs are returned.

Query String
fqn

Fully-qualifed name of a job to return (job::/sandbox/admin::myjob, e.g.). If the matchPartialFQN query parameter is true then this parameter can specify a namespace (job::/sandbox/admin, e.g.) and all jobs in that namespace are returned.

Query String
health

If true, the health field in each Job object in the response includes JobHealth metrics.

Query String (boolean)
ids

List of job UUIDs. Only jobs with the specified UUIDs are returned.

Query String [ ]
, comma separated (ids=aaa,bbb)
matchPartialFQN

If true all jobs in the namespace specified by the fqn query parameter are returned.

Query String (boolean)
package_id

UUID of a existing package. Only jobs that use the specified package are returned.

Query String
page

Specifies the number of the results page to fetch. By default, the first page of results is returned.

Query String
ProviderFQN

A Provider FQN. Only jobs bound to services on the specified provider are returned.

Query String
ServiceFQN

A Service FQN. Only jobs bound to the specified service are returned.

Query String
tag

List of tags. Only jobs with the specified tags are returned.

Query String [ ]
, comma separated (tag=aaa,bbb)

Response

200 OK

A successful response contains an list of Job objects.

Response example
[
{
"aggregate_network_routes": null,
"created_at": "2017-03-30T23:20:47.930605022Z",
"created_by": "admin@apcera.com",
"fqn": "job::/sandbox/admin::api-bootprint",
"logs": [
{
"channel": "job.$JOB_UUID.$INSTANCE_UUID.stdout",
"file": "/logs/stdout.*.log"
},
{
"channel": "job.$JOB_UUID.$INSTANCE_UUID.stderr",
"file": "/logs/stderr.*.log"
}
],
"name": "api-bootprint",
"network_ref": null,
"num_instances": 1,
"packages": [
{
"source": "user",
"state": "unknown",
"uuid": "f02708d1-b5f5-4a54-9158-9ff540a37b0f"
},
{
"source": "system",
"state": "ready",
"uuid": "03279c73-9d31-4940-91f0-288cbb44df74"
},
{
"source": "system",
"state": "ready",
"uuid": "558e83d1-66a4-4554-84e2-63b04c79f7fe"
},
{
"source": "system",
"state": "ready",
"uuid": "f02708d1-b5f5-4a54-9158-9ff540a37b0f"
}
],
"ports": [
{
"number": 0,
"optional": false,
"routes": [
{
"auto_provision": true,
"endpoint": "api-bootprint-bpaezi.example.com",
"https_only": false,
"type": "http",
"weight": 0
}
]
}
],
"processes": {
"app": {
"start_command": "",
"start_command_raw": [
],
"start_command_timeout": 30,
"stop_command": "",
"stop_command_raw": [
],
"stop_timeout": 5
}
},
"resources": {
"cpu": 0,
"disk": 1073741824,
"memory": 268435456,
"netmax": 0,
"network": 5000000
},
"restart": {
"restart_mode": "always"
},
"rollout": {
"errored_state_window": 0,
"flapping_minimum_restarts": 3,
"flapping_percent": 0.5,
"flapping_window": 300,
"force_stop_old_instances_after": 120
},
"state": "started",
"tags": {
"app": "api-bootprint"
},
"updated_at": "2017-03-30T23:20:53.654590949Z",
"updated_by": "admin@apcera.com",
"uuid": "62dc76d9-8d1c-475c-86f6-7a22d646084a",
"version_id": 2
},
{
"aggregate_network_routes": null,
"bindings": {
"binding::/::19f4d072-7850-4722-8fdf-559e069b7e28": {
"env_var": [
"MLINK_URI"
],
"fqn": "binding::/::19f4d072-7850-4722-8fdf-559e069b7e28",
"job_fqn": "job::/sandbox/admin::api-docs",
"name": "mlink",
"target_job_fqn": "job::/sandbox/admin::foo",
"target_job_uuid": "ed933cf1-4026-4ffd-9033-6ffff5d802c7"
},
"binding::/::4fe92aad-4ce4-406d-9182-bec4108449a4": {
"env_var": [
"MLINK_URI"
],
"fqn": "binding::/::4fe92aad-4ce4-406d-9182-bec4108449a4",
"job_fqn": "job::/sandbox/admin::api-docs",
"name": "mlink",
"target_job_fqn": "job::/sandbox/admin::foo",
"target_job_uuid": "ed933cf1-4026-4ffd-9033-6ffff5d802c7"
}
},
"created_at": "2017-03-27T23:47:37.164719871Z",
"created_by": "admin@apcera.com",
"fqn": "job::/sandbox/admin::api-docs",
"logs": [
{
"channel": "job.$JOB_UUID.$INSTANCE_UUID.stdout",
"file": "/logs/stdout.*.log"
},
{
"channel": "job.$JOB_UUID.$INSTANCE_UUID.stderr",
"file": "/logs/stderr.*.log"
}
],
"name": "api-docs",
"network_ref": null,
"num_instances": 1,
"packages": [
{
"source": "user",
"state": "unknown",
"uuid": "fbcd6ee8-4dda-4ca4-8475-7ad21ea214c3"
},
{
"source": "system",
"state": "ready",
"uuid": "03279c73-9d31-4940-91f0-288cbb44df74"
},
{
"source": "system",
"state": "ready",
"uuid": "558e83d1-66a4-4554-84e2-63b04c79f7fe"
},
{
"source": "system",
"state": "ready",
"uuid": "fbcd6ee8-4dda-4ca4-8475-7ad21ea214c3"
}
],
"ports": [
{
"number": 0,
"optional": false,
"routes": [
{
"auto_provision": true,
"endpoint": "api-docs-t7cwrf.example.com",
"https_only": false,
"type": "http",
"weight": 0
}
]
}
],
"processes": {
"app": {
"start_command": "",
"start_command_raw": [
],
"start_command_timeout": 30,
"stop_command": "",
"stop_command_raw": [
],
"stop_timeout": 5
}
},
"resources": {
"cpu": 0,
"disk": 1073741824,
"memory": 268435456,
"netmax": 0,
"network": 5000000
},
"restart": {
"restart_mode": "always"
},
"rollout": {
"errored_state_window": 0,
"flapping_minimum_restarts": 3,
"flapping_percent": 0.5,
"flapping_window": 300,
"force_stop_old_instances_after": 120
},
"state": "stopped",
"tags": {
"app": "api-docs"
},
"updated_at": "2017-03-30T22:17:30.232645006Z",
"updated_by": "admin@apcera.com",
"uuid": "8cf12f8a-6133-4cf9-9737-3506792e5cfb",
"version_id": 5
}
]

POST /jobs

Creates a new job from the Job object passed in the POST body.

MIME Types

Request
Accept: application/vnd.apcera.jobs;version=1
Content-Type: application/vnd.apcera.jobs;version=1
Response
Content-Type: application/vnd.apcera.jobs;version=1

Request Parameters

None.

Request body

Job object with required properties.

Response

200 OK

A successful response returns the newly created Job object.

Response Headers

Name Description Type
location

API endpoint to retrieve the newly created job.

string

Response example
{
"aggregate_network_routes": null,
"created_at": "2017-04-03T17:07:42.150584599Z",
"created_by": "admin@apcera.com",
"fqn": "job::/sandbox/admin::api-test-1",
"logs": [
{
"channel": "job.$JOB_UUID.$INSTANCE_UUID.stdout",
"file": "/logs/stdout.*.log"
},
{
"channel": "job.$JOB_UUID.$INSTANCE_UUID.stderr",
"file": "/logs/stderr.*.log"
}
],
"name": "api-test-1",
"network_ref": null,
"num_instances": 1,
"packages": [
],
"processes": {
},
"resources": {
"cpu": 0,
"disk": 0,
"memory": 0,
"netmax": 0,
"network": 0
},
"restart": {
"restart_mode": "always"
},
"rollout": {
"errored_state_window": 0,
"flapping_minimum_restarts": 3,
"flapping_percent": 0.5,
"flapping_window": 300,
"force_stop_old_instances_after": 120
},
"state": "created",
"updated_at": "2017-04-03T17:07:42.150584599Z",
"updated_by": "",
"uuid": "e3b3f569-5eb2-4d82-892c-48a7c6577387",
"version_id": 1
}

POST /jobs/docker

Creates a new application from a Docker image. The operation is asynchronous: a successful response is the URI of the corresponding Task object you use to monitor the operation's progress. There are two ways to use this URI to track progress of the operation: you can poll the URI over HTTP, or you can stream TaskEvent objects over a WebSocket connection.

MIME Types

Request
Accept: application/vnd.apcera.taskref;version=1
Content-Type: application/vnd.apcera.dockerjobcreate;version=1
Response
Content-Type: application/vnd.apcera.taskref;version=1

Request Parameters

None.

Request body

CreateDockerJobRequest object with required properties.

Response

200 OK

A successful response returns a TaskResponse that contains the URL of the corresponding Task object you use to track the operation's progress.

Response example
{
"location": "http://api.example.com/tasks/7be01f51-f9d1-4d62-8b0a-2265e10fd4f0"
}

GET /jobs/health

Returns health information for one or more jobs. If a job UUID is supplied that corresponds to a deleted or non-running job, or if the requesting user does not have permit read policy permissions on a requested job, then health information is not returned for that job.

MIME Types

Request
Accept: application/vnd.apcera.jobhealth;version=1
Response
Content-Type: application/vnd.apcera.jobhealth;version=1

Request Parameters

Name Description Location Data Type Notes
ids

List of job UUIDs.

Query String [ ]
, comma separated (ids=aaa,bbb)
Required

Response

200 OK

Successful response is a list of JobHealth.

Response example
[
{
"flapping": false,
"instance_state_count": {
"RUNNING": 3
},
"score": 1,
"uuid": "47920f21-6c79-41cf-8d88-7ff3b6962cb8"
},
{
"flapping": false,
"instance_state_count": {
"SETUP": 2
},
"score": 0,
"uuid": "1c8f6482-1170-421d-92d8-9eb20e17c8e4"
}
]

GET /jobs/routes

Returns a list of route endpoints mapped to an array of UUIDs of jobs using each route.

MIME Types

Request
Accept: application/vnd.apcera.routemap;version=1
Response
Content-Type: application/vnd.apcera.routemap;version=1

Request Parameters

None.

Response

200 OK

Successful response.

Response example
{
"10.0.0.97:38238": [
"4741f275-2e4e-480a-88a4-c16df59cb5c7"
],
"apcera-api-training.example.io": [
"47920f21-6c79-41cf-8d88-7ff3b6962cb8"
],
"app4.kiso.io": [
"7f1318fd-fb01-43dd-9e09-881ffe7cf219",
"268a2eac-a545-46b8-9213-babe54949661"
]
}

GET /jobs/routes/{endpoint}

Returns a list of UUIDs for jobs that use the specified endpoint.

MIME Types

Request
Accept: application/vnd.apcera.routemap;version=1
Response
Content-Type: application/vnd.apcera.routemap;version=1

Request Parameters

Name Description Location Data Type Notes
endpoint

Base64-encoded endpoint URL.

Path String
Required

Response

200 OK

Successful response is a map of the route endpoint to an array of jobs using that endpoint.

Response example
{
"app-route.example.io": [
"7f1318fd-fb01-43dd-9e09-881ffe7cf219",
"268a2eac-a545-46b8-9213-babe54949661"
]
}
400 Bad Request

Malformed request. Make sure the URL endpoint is URL-safe Base64-encoded.

DELETE /jobs/{uuid}

Deletes the specified job.

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the job to delete.

Path String
Required

Response

200 OK

Successful response is empty.

404 Not Found

Job not found.

GET /jobs/{uuid}

Returns details about the specified job.

MIME Types

Request
Accept: application/vnd.apcera.job;version=1
Response
Content-Type: application/vnd.apcera.job;version=1

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the job to fetch.

Path String
Required

Response

200 OK

Successful response.

Response example
{
"aggregate_network_routes": null,
"created_by": "admin",
"fqn": "job::/sandbox/admin::app4",
"logs": [
{
"channel": "job.$JOB_UUID.$INSTANCE_UUID.stdout",
"file": "/logs/stdout.*.log"
},
{
"channel": "job.$JOB_UUID.$INSTANCE_UUID.stderr",
"file": "/logs/stderr.*.log"
}
],
"name": "app4",
"network_ref": null,
"num_instances": 1,
"packages": [
{
"source": "user",
"state": "unknown",
"uuid": "ee91ab6c-3879-493d-94db-d9012c109905"
},
{
"source": "system",
"state": "ready",
"uuid": "03279c73-9d31-4940-91f0-288cbb44df74"
}
],
"ports": [
{
"number": 0,
"optional": false,
"routes": [
{
"auto_provision": true,
"endpoint": "app4.example.com",
"https_only": false,
"type": "http",
"weight": 0
}
]
}
],
"processes": {
"app": {
"start_command": "",
"start_command_raw": [
],
"start_command_timeout": 30,
"stop_command": "",
"stop_command_raw": [
],
"stop_timeout": 5
}
},
"resources": {
"cpu": 0,
"disk": 1073741824,
"memory": 268435456,
"netmax": 0,
"network": 5000000
},
"restart": {
"restart_mode": "always"
},
"rollout": {
"errored_state_window": 0,
"flapping_minimum_restarts": 3,
"flapping_percent": 0.5,
"flapping_window": 300,
"force_stop_old_instances_after": 120
},
"state": "started",
"tags": {
"app": "app4"
},
"updated_at": "2017-04-03T22:37:23.022240787Z",
"updated_by": "admin",
"uuid": "a6c6113e-e6fa-4bdc-96f5-26bb7534ab85",
"version_id": 2
}
404 Not Found

Job not found.

PUT /jobs/{uuid}

Updates the specified job.

MIME Types

Request
Accept: application/vnd.apcera.job;version=1
Content-Type: application/vnd.apcera.job;version=1
Response
Content-Type: application/vnd.apcera.job;version=1

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the job to update.

Path String
Required

Request body

Job object with required properties.

Response

200 OK

A successful response contains the updated Job object.

GET /jobs/{uuid}/files/{path}

Returns information about a running job instance's file system.

MIME Types

Request
Accept: application/octet-stream,text/plain
Response
Content-Type: application/octet-stream,text/plain

Request Parameters

Name Description Location Data Type Notes
path

The path to the root folder for which to generate the folder/file listing. For example, /jobs/<uuid>/files/ returns a listing for the instance's root folder; /jobs/<uuid>/files/app. returns a list of the instance's /app folder.

Path String
Required
uuid

UUID of the job whose file system information should be retrieved.

Path String
Required

Response

200 OK

A successful response returns a list of folders and files in the specified path.

Response example
[
{
"name": "helloworld/",
"size": "-"
},
{
"name": "lib/",
"size": "-"
},
{
"name": "setup.py",
"size": "1216"
},
{
"name": "gunicorn.config",
"size": "69"
}
]

GET /jobs/{uuid}/instances

Returns instances from the health manager for a given job UUID.

MIME Types

Request
Accept: application/vnd.apcera.instance;version=1
Response
Content-Type: application/vnd.apcera.instance;version=1

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the job.

Path String
Required

Response

200 OK

Successful response is a list of Instance objects representing job instances running on the cluster.

Response example
[
{
"announced_routes": true,
"created_time": "2017-04-03T23:55:18.572352846Z",
"exit_code": 0,
"exited": false,
"failed": false,
"host": "examplecluster-4c8845ef",
"instance_manager_uuid": "3fe3aace-d2d8-4e78-8750-a7fe688ac985",
"job_version_id": 3,
"state": "RUNNING",
"uuid": "a4b25c83-0320-4d6b-929a-7ef9a74fcc71"
},
{
"announced_routes": true,
"created_time": "2017-04-04T22:44:55.928932841Z",
"exit_code": 0,
"exited": false,
"failed": false,
"host": "examplecluster-037ffac0",
"instance_manager_uuid": "bb1042d5-40f1-4fa2-9b1b-666f8f90ce67",
"job_version_id": 3,
"state": "RUNNING",
"uuid": "ba5f265c-5479-4e83-9326-49cb1fb9ceac"
}
]

DELETE /jobs/{uuid}/instances/{instance_uuid}

Issues a stop request to the specified job instance.

Request Parameters

Name Description Location Data Type Notes
instance_uuid

UUID of the job instance to stop.

Path String
Required
uuid

UUID of the job.

Path String
Required

Response

200 OK

Successful response.

POST /jobs/{uuid}/instances/{instance_uuid}/snapshot

Issues a snapshot request to the specified job instance. The snapshot process is asynchronous. The endpoint's response contains a Location header whose value is the GET /packages/{uuid} endpoint to retrieve the newly created package's metadata. API clients should poll this endpoint until the package's state transitions from "uploading" to "ready".

MIME Types

Request
Accept: application/vnd.apcera.package;version=1
Response
Content-Type: application/vnd.apcera.package;version=1

Request Parameters

Name Description Location Data Type Notes
directory

Directory of a given job/capsule to snapshot.

Query String
instance_uuid

UUID of the instance to be snapshotted.

Path String
Required
pkgFQN

FQN of snapshot package to return.

Query String
Required
uuid

UUID of the job to be snapshotted.

Path String
Required

Response

200 OK

A successful response indicates the snapshot was created successfully.

Response Headers

Name Description Type
Location

The GET /packages/{uuid} API endpoint to retrieve the newly created Package object (http://api.example.com/packages/a57ba7cb-bfb1-451f-9fd8-fd590d2d947e, for example).

string

GET /jobs/{uuid}/logs

Returns log items for the specified job.

MIME Types

Request
Accept: application/octet-stream
Response
Content-Type: application/octet-stream

Request Parameters

Name Description Location Data Type Notes
Last-Event-ID

ID of a log event. Only events newer than the specified event are returned in the response. Alternatively, you can use the lastEventId query parameter to specify this value.

Header String
lastEventId

ID of a log event. Only events newer than the specified event are returned in the response. Alternatively, you can use the Last-Event-ID HTTP header to specify this value.

Query String
lines

Number of log lines to return in a response.

Query Integer
tail

If present in request query new log lines are sent to the client as they are generated on the cluster.

Query String
uuid

UUID of the job to retrieve logs for.

Path String
Required

Response

200 OK

Successful response is a stream of log messages from the application.

GET /jobs/{uuid}/logs/drains

Returns all configured log drains for the specified job.

MIME Types

Request
Accept: application/vnd.apcera.drain;version=1
Response
Content-Type: application/vnd.apcera.drain;version=1

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the job to retrieve log drains for.

Path String
Required

Response

200 OK

Successful response.

Response example
[
{
"conf": {
"priority": 0,
"protocol": ""
},
"max_size": 2048,
"url": "syslog://10.0.0.97:16585",
"uuid": "39758bd9-6fc2-4e7c-963a-7cb0e22ecb93"
}
]

POST /jobs/{uuid}/logs/drains

Creates a log drain on the specified job.

MIME Types

Request
Accept: application/vnd.apcera.drain;version=1
Content-Type: application/vnd.apcera.drain;version=1
Response
Content-Type: application/vnd.apcera.drain;version=1

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the job.

Path String
Required

Request body

Drain object with required properties.

Response

200 OK

Successful response.

DELETE /jobs/{uuid}/logs/drains/{drain_uuid}

Deletes the specified log drain from the specified job.

Request Parameters

Name Description Location Data Type Notes
drain_uuid

UUID of the log drain to delete.

Path String
Required
uuid

UUID of the job with the log drain to delete.

Path String
Required

Response

200 OK

Successful response is the updated job object.

POST /manifests

Deploys a multi-resource manifest that declares and configures one or more jobs, services, and networks. A successful request starts an asynchronous process on the Apcera cluster that parses and executes the manifest, creating each job, service or network declared in the manifest. You can track the status of the asynchronous operation with the location of the Task object returned in a successful response.

MIME Types

Request
Accept: application/vnd.apcera.manifestresponse;version=1
Content-Type: application/vnd.apcera.jobmanifest;version=1
Response
Content-Type: application/vnd.apcera.manifestresponse;version=1

Request Parameters

None.

Request body

Manifest object with required properties.

Response

200 OK

A successful response contains a ManifestResponse object.

Response example
{
"expanded_json": "",
"expanded_manifest": {
},
"location": "http://api.example.com/tasks/317c792f-3d59-42ac-866e-ad25ca871cbc",
"warnings": ""
}

GET /namespace/default

Returns the default namespace for the currently logged-in user.

MIME Types

Request
Accept: application/vnd.apcera.namespace;version=1
Response
Content-Type: application/vnd.apcera.namespace;version=1

Request Parameters

None.

Response

200 OK

Successful response.

Response example
{
"namespace": "/sandbox/tim.statler"
}

GET /networks

Returns a list of VirtualNetwork objects.

MIME Types

Request
Accept: application/vnd.apcera.network;version=1
Response
Content-Type: application/vnd.apcera.network;version=1

Request Parameters

Name Description Location Data Type Notes
fqn

FQN used to filter the list of networks returned. Can be a partial FQN (network::/sandbox/admin, e.g.) if the matchPartialFQN query parameter is set to true.

Query String
matchPartialFQN

If true any networks that partially match the specified FQN are returned. If false the fqn query parameter must specify a complete network FQN.

Query Boolean

Response

200 OK

Successful response.

Response example
[
{
"created_at": "2015-11-14T15:09:18.370605568Z",
"created_by": "admin@apcera.me",
"description": "",
"fqn": "network::/sandbox/admin::net2",
"name": "net2",
"network_end_points": [
{
"end_point_interface": [
{
"hardware_addr": "6a:4f:33:9d:90:92",
"ipv4_addr": "192.168.1.1/24"
}
],
"job_fqn": "job::/sandbox/admin::myapp",
"network_fqn": "network::/sandbox/admin::net2",
"uuid": "cf907332-d3b6-4760-84ef-0fa937f2f383"
},
{
"job_fqn": "job::/sandbox/admin::other-app",
"network_fqn": "network::/sandbox/admin::net2",
"uuid": "4193dd32-ec07-464d-9c75-a53e31b8b1dc"
},
{
"end_point_interface": [
{
"hardware_addr": "de:d8:65:63:7f:a2",
"ipv4_addr": "192.168.1.2/24"
}
],
"job_fqn": "job::/sandbox/admin::guide",
"network_fqn": "network::/sandbox/admin::net2",
"uuid": "84bdcbf5-c8b0-445b-9e97-8d2e0b3478e4"
}
],
"subnet_info": {
"Subnet": "192.168.1.0/24"
},
"updated_at": "2015-11-17T22:25:03.555900207Z",
"updated_by": "",
"uuid": "e4893f6c-4ed1-4bca-8e7e-f3a7dd56a188",
"version_id": 0
}
]

POST /networks

Creates a new VirtualNetwork.

MIME Types

Request
Accept: application/vnd.apcera.network;version=1
Content-Type: application/vnd.apcera.network;version=1
Response
Content-Type: application/vnd.apcera.network;version=1

Request Parameters

None.

Request body

VirtualNetwork object with required properties.

Response

200 OK

Successful response.

Response Headers

Name Description Type
Location

The GET /networks/{uuid} API endpoint to retrieve newly created virtual network (http://api.example.com/networks/a57ba7cb-bfb1-451f-9fd8-fd590d2d947e, for example).

string

DELETE /networks/{uuid}

Deletes the specified VirtualNetwork.

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the virtual network to delete.

Path String
Required

Response

200 OK

Network deleted successfully.

GET /networks/{uuid}

Returns the specified VirtualNetwork.

MIME Types

Request
Accept: application/vnd.apcera.network;version=1
Response
Content-Type: application/vnd.apcera.network;version=1

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the virtual network to describe.

Path String
Required

Response

200 OK

Successful response.

GET /packages

Returns a list of packages on the cluster, optionally filtered by package name, FQN, UUID or other properties. Pagination is also supported.

MIME Types

Request
Accept: application/vnd.apcera.package;version=1
Response
Content-Type: application/vnd.apcera.package;version=1

Request Parameters

Name Description Location Data Type Notes
excluded_tags

List of excluded tags to filter by. Only packages without the specified tags are returned.

Query String [ ]
, comma separated (excluded_tags=aaa,bbb)
fqn

FQN of package to return.

Query String
ids

List of package UUIDs. Only packages with specifed UUIDs to return.

Query String [ ]
, comma separated (ids=aaa,bbb)
matchPartialFQN

If true, packages that partially match the FQN specified by fqn parameter are returned. If false (default) then fqn must exactly match an available package.

Query String (boolean)
name

Local name of package to return.

Query String
package_id

UUID of the package to return.

Query String
provides_name

Name that describes the packages to return. Value can be an exact package name ('java-1.6' or 'ubuntu-13.10', for example) or a generalized requirement ('linux', for example).

Query String
provides_type

Type of packages to return.

Query String , valid values:
  • "file"
  • "package"
  • "runtime"
  • "os"
tag

List of tags to filter by. Only packages with the specified tags are returned.

Query String [ ]
, comma separated (tag=aaa,bbb)

Response

200 OK

Successful response.

POST /packages

Creates a new Package object that contains meta-data about the package, including its name, FQN, and dependencies. It also contains information about the binary package resource(s) associated with the package, including the content length and hash digest of each resource, which you must calculate before calling this endpoint. A successful response contains the newly created package object with its state field set to "uploading". The package remains in this state until all packages resources referenced by the package have been uploaded via the PUT /packages/{packageid}/resources/{resourceid} endpoint. Once all package resources have been successfully uploaded the package state is set to "ready". Only packages in the "ready" state can be used with a job.

MIME Types

Request
Accept: application/vnd.apcera.package;version=1
Content-Type: application/vnd.apcera.package;version=1
Response
Content-Type: application/vnd.apcera.package;version=1

Request Parameters

None.

Request body

Package object with required properties.

Response

200 OK

Successful completion returns the definition of the newly created package.

Response Headers

Name Description Type
Location

The GET /packages/{uuid} API endpoint to retrieve newly created Package object (http://api.example.com/packages/a57ba7cb-bfb1-451f-9fd8-fd590d2d947e, for example).

string

Response example
{
"created_at": "2017-07-25T18:20:16.27581675Z",
"created_by": "admin@apcera.me",
"fqn": "package::/sandbox/admin::a_package",
"name": "a_package",
"resource": {
"digest": "sha256:fb3e36370f543779709e6a9b3e509cd814ae7f079201ce8b42a5f66415e81154",
"length": 42,
"uuid": "b6ae912a-7682-4ca7-979e-6a77439a9cbc"
},
"resources": [
{
"digest": "sha256:fb3e36370f543779709e6a9b3e509cd814ae7f079201ce8b42a5f66415e81154",
"length": 42,
"uuid": "b6ae912a-7682-4ca7-979e-6a77439a9cbc"
}
],
"state": "uploading",
"updated_at": "2017-07-25T18:20:16.27581675Z",
"updated_by": "",
"uuid": "dce21834-bf00-4dbd-94ac-2f7f39a85498",
"version_id": 1
}

POST /packages/dependencies

Returns a list of packages that fulfill the specified dependency type and name for the specified namespace.

MIME Types

Request
Accept: application/vnd.apcera.package;version=1
Content-Type: application/vnd.apcera.packagedependencies;version=1
Response
Content-Type: application/vnd.apcera.package;version=1

Request Parameters

None.

Request body

PackageDependsRequest object with required properties.

Response

200 OK

Successful response is a list of Package objects.

POST /packages/docker

Creates a new package from a Docker image. The operation is asynchronous: a successful response is the URI of the corresponding Task object you use to monitor the operation's progress. There are two ways to use this URI to track progress of the operation: you can poll the URI over HTTP, or you can stream TaskEvent objects over a WebSocket connection.

MIME Types

Request
Accept: application/vnd.apcera.taskref;version=1
Content-Type: application/vnd.apcera.dockerpackagecreate;version=1
Response
Content-Type: application/vnd.apcera.taskref;version=1

Request Parameters

None.

Request body

CreateDockerPackageRequest object with required properties.

Response

200 OK

A successful response returns a TaskResponse that contains the URL of the corresponding Task object you use to track the operation's progress.

Response example
{
"location": "http://api.example.com/tasks/7be01f51-f9d1-4d62-8b0a-2265e10fd4f0"
}

GET /packages/{package_uuid}/resources/{resource_uuid}

Downloads the specified resource from the specified package.

MIME Types

Request
Accept: application/octet-stream
Response
Content-Type: application/octet-stream

Request Parameters

Name Description Location Data Type Notes
package_uuid

UUID of the package.

Path String
Required
resource_uuid

UUID of the package resource.

Path String
Required

Response

200 OK

Successful response.

PUT /packages/{package_uuid}/resources/{resource_uuid}

Uploads a package resource for the specified package.

MIME Types

Request
Accept: application/vnd.apcera.taskref;version=1
Content-Type: application/octet-stream
Response
Content-Type: application/vnd.apcera.taskref;version=1

Request Parameters

Name Description Location Data Type Notes
Content-Digest

A SHA-1, SHA-256, SHA-384, or SHA-512 hash of a binary package resource bein uploaded. The hash value must be prefixed with sha1:, sha256:, sha384:, or sha512:, depending on the hash function used (for example: sha1:3c650b19716f3fe6ca293fbf78795f45ba684ea6). The specified value must match the value specified when the package was created with POST /packages.

Header String
Required
Content-Length

Length of the binary resource in bytes. The specified value must match the value specified when the package was created with POST /packages.

Header String
Required
package_uuid

UUID of the package.

Path String
Required
resource_uuid

UUID of the resource.

Path String
Required

Request body

Response

200 OK

Successful response.

DELETE /packages/{uuid}

Deletes the specified package. An error is returned if the package is in use by a job.

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the package to delete.

Path String
Required

Response

200 OK

Successful response.

GET /packages/{uuid}

Returns the specified Package object.

MIME Types

Request
Accept: application/vnd.apcera.package;version=1
Response
Content-Type: application/vnd.apcera.package;version=1

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the package.

Path String
Required

Request body

Response

200 OK

Successful response.

PUT /packages/{uuid}

Updates the specified package with the properties defined in the provided package object.

MIME Types

Request
Accept: application/vnd.apcera.package;version=1
Content-Type: application/vnd.apcera.package;version=1
Response
Content-Type: application/vnd.apcera.package;version=1

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the package.

Path String
Required

Request body

Package object with required properties.

Response

200 OK

Successful response.

GET /providers

Returns a list of ProviderInfo objects, optionally filtered by namespace.

MIME Types

Request
Accept: application/vnd.apcera.providerinfo;version=1
Response
Content-Type: application/vnd.apcera.providerinfo;version=1

Request Parameters

Name Description Location Data Type Notes
fqn

Fully-qualifed name of a provider to return (service::/sandbox/admin::my-service, e.g.). If the matchPartialFQN query parameter is true then this parameter can specify just a namespace (job::/sandbox/admin, e.g.) and any providers in that namespace are returned.

Query String
matchPartialFQN

If true all providers in the namespace specified by the fqn query parameter are returned.

Query String (boolean)

Response

200 OK

Successful response is a list of Provider objects that matched the query.

Response example
[
{
"created_at": "2017-07-24T23:16:52.454188591Z",
"created_by": "admin@apcera.me",
"description": "",
"extended_status": {
},
"fqn": "provider::/apcera/providers::apcfs",
"gateway_id": "1699eaf1-cd6a-4009-8c4b-99f2cfdd34b2",
"name": "apcfs",
"state": "",
"status": "created",
"type": "nfs",
"uuid": "a1bd8fd1-5a59-4813-829a-fbd6e5f34b2d"
}
]

POST /providers

Creates a new provider.

MIME Types

Request
Accept: application/vnd.apcera.providerinfo;version=1
Content-Type: application/vnd.apcera.providerinfo;version=1
Response
Content-Type: application/vnd.apcera.providerinfo;version=1

Request Parameters

None.

Request body

CreateProviderRequest object with required properties.

Response

200 OK

Successful response is a ProviderInfo object representing the new provider.

Response example
{
"backing_job_fqn": "job::/sandbox/admin::docker-mysql-server",
"backing_job_port": "3306",
"created_at": "2017-06-01T16:40:07.287414209Z",
"created_by": "admin@apcera.com",
"description": "",
"extended_status": {
},
"fqn": "provider::/sandbox/admin/providers::docker-mysql-provider",
"gateway_id": "acb356a7-e667-4eab-98ad-2dbd3e49cddb",
"name": "docker-mysql-provider",
"state": "",
"status": "created",
"type": "mysql",
"uuid": "9ae28e2a-32fc-4138-839b-c3c8a9da8c03"
}

DELETE /providers/{uuid}

Deletes the specified provider. The provider cannot be deleted if it has existing services. You must first delete the services created using the provider with the DELETE /services/{uuid}.

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the provider to delete.

Path String
Required

Response

200 OK

Successful response is empty.

GET /routes

Returns a list of routes.

MIME Types

Request
Accept: application/vnd.apcera.route;version=1
Response
Content-Type: application/vnd.apcera.route;version=1

Request Parameters

Name Description Location Data Type Notes
endpoint

Route endpoint.

Query String
uuid

Job UUID.

Query String (string)

Response

200 OK

Successful response.

POST /routes

Creates a new route.

MIME Types

Request
Accept: application/vnd.apcera.route;version=1
Content-Type: application/vnd.apcera.route;version=1
Response
Content-Type: application/vnd.apcera.route;version=1

Request Parameters

None.

Request body

Route object with required properties.

Response

200 OK

Successful response.

DELETE /routes/{uuid}

Deletes the specified route.

MIME Types

Request
Accept: application/vnd.apcera.route;version=1
Response
Content-Type: application/vnd.apcera.route;version=1

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the route to delete.

Path String (string)
Required

Request body

Response

200 OK

Successful response.

GET /routes/{uuid}

Returns the route specified by the UUID.

MIME Types

Request
Accept: application/vnd.apcera.route;version=1
Response
Content-Type: application/vnd.apcera.route;version=1

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the route.

Path String (string)
Required

Response

200 OK

Successful response.

PUT /routes/{uuid}

Updates the specified route with the properties defined in the provided route object.

MIME Types

Request
Accept: application/vnd.apcera.route;version=1
Content-Type: application/vnd.apcera.route;version=1
Response
Content-Type: application/vnd.apcera.route;version=1

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the route.

Path String (string)
Required

Request body

Route object with required properties.

Response

200 OK

Successful response.

GET /rules

Lists event rules used by semantic pipelines.

MIME Types

Request
Accept: application/vnd.apcera.speventrule;version=1
Response
Content-Type: application/vnd.apcera.speventrule;version=1

Request Parameters

None.

Response

200 OK

Successful response.

Response example
[
{
"action": {
"commands": [
"delete"
],
"inline": "deny"
},
"created_at": "2014-08-07T18:52:52.017254975Z",
"created_by": "",
"fqn": "sempiperule::/::nodelete",
"job": null,
"name": "nodelete",
"provider": null,
"service": "service::/::mydb10",
"type": 0,
"uuid": "aaf3923a-8f97-45a1-977c-0dacb2ba078a",
"version_id": 1
},
{
"action": {
"commands": [
"delete",
"drop"
],
"inline": "deny"
},
"created_at": "2014-08-22T17:54:12.161481714Z",
"created_by": "",
"fqn": "sempiperule::/sandbox/joe.user::no-delete-drop",
"job": null,
"name": "no-delete-drop",
"provider": "provider::/::postgres",
"service": "service::/sandbox/joe.user::tododb",
"type": 0,
"uuid": "6d6c1f78-85b7-4e9f-8a81-a5e996de8b8f",
"version_id": 1
}
]

POST /rules

Creates a new semantic pipeline rule for governing a given provider's behavior.

MIME Types

Request
Accept: application/vnd.apcera.speventrule;version=1
Content-Type: application/vnd.apcera.speventrule;version=1
Response
Content-Type: application/vnd.apcera.speventrule;version=1

Request Parameters

None.

Request body

SemiPipeRule object with required properties.

Response

200 OK

Successful response.

Response Headers

Name Description Type
Location

The GET /rules/{uuid} API endpoint to retrieve newly created rule (http://api.example.com/rules/a57ba7cb-bfb1-451f-9fd8-fd590d2d947e, for example).

string

DELETE /rules/{uuid}

Deletes a policy event rule.

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the rule.

Path String
Required

Response

200 OK

Successful response.

GET /rules/{uuid}

Returns information about a rule that that controls the behavior of semantic pipelines.

MIME Types

Request
Accept: application/vnd.apcera.speventrule;version=1
Response
Content-Type: application/vnd.apcera.speventrule;version=1

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the rule.

Path String
Required

Response

200 OK

Successful response.

GET /runtimes

Lists file names and patterns used by APC to determine the appropriate staging pipeline to stage a set of local source files.

MIME Types

Request
Accept: application/vnd.apcera.runtime;version=1
Response
Content-Type: application/vnd.apcera.runtime;version=1

Request Parameters

None.

Response

200 OK

Successful response.

Response example
[
{
"patterns": [
"bash_start.sh",
"bash_setup.sh"
],
"runtime": "bash"
},
{
"patterns": [
"*.rb",
"Gemfile",
"Gemfile.lock"
],
"runtime": "ruby"
},
{
"patterns": [
"package.json",
"node_modules",
"*.js"
],
"runtime": "nodejs"
},
{
"patterns": [
"pom.xml",
"*.jar",
"*.war",
"*.java"
],
"runtime": "java"
},
{
"patterns": [
"Makefile.PL",
"Build.PL",
"META.yml",
"META.json"
],
"runtime": "perl"
},
{
"patterns": [
"*.php",
"php.ini"
],
"runtime": "php"
},
{
"patterns": [
"*.py",
"runtime.txt",
"manage.py"
],
"runtime": "python"
},
{
"patterns": [
"*.go"
],
"runtime": "go"
},
{
"patterns": [
"index.html"
],
"runtime": "static-site"
}
]

DELETE /secrets

Deletes the specified secret.

Request Parameters

Name Description Location Data Type Notes
fqn

The fully qualified name the secret to delete.

Query String

Response

200 OK

Successful response.

GET /secrets

Lists secrets. To return a particular secret or a set based on namespace, specify the fqn query parameter. The filter query parameter will list secrets of the designated filter type.

MIME Types

Request
Accept: application/vnd.apcera.secret;version=1
Response
Content-Type: application/vnd.apcera.secret;version=1

Request Parameters

Name Description Location Data Type Notes
filter

The filter designation of the secret type to retrieve. Possible values are 'certificate', 'private' or 'all'

Query String
fqn

The fully qualified name the secret(s) to retrieve.

Query String
matchPartialFQN

If true, secrets that partially match the specified FQN are returned.

Query String (boolean)

Response

200 OK

Successful response.

POST /secrets

Imports a new secret.

MIME Types

Request
Content-Type: application/vnd.apcera.secret;version=1

Request Parameters

None.

Request body

SecretCreateRequest object with required properties.

Response

200 OK

Successful response.

DELETE /secrets/domains

Uninstalls the specified domain.

Request Parameters

Name Description Location Data Type Notes
domain

The name of the domain to uninstall.

Query String

Response

200 OK

Successful response.

GET /secrets/domains

Lists domains/certificates installed on the router. To return a domain(s) which is using a particular secret, specify the fqn query parameter. The domain query parameter will return the specified domain.

MIME Types

Request
Accept: application/vnd.apcera.secretinstall;version=1
Response
Content-Type: application/vnd.apcera.secretinstall;version=1

Request Parameters

Name Description Location Data Type Notes
domain

Returns the certificate/private-key for the specified domain.

Query String
fqn

The fully qualified name the secret(s) to retrieve.

Query String

Response

200 OK

Successful response.

POST /secrets/domains

Installs a new domain.

MIME Types

Request
Content-Type: application/vnd.apcera.secretinstall;version=1

Request Parameters

None.

Request body

SecretInstall object with required properties.

Response

200 OK

Successful response.

GET /services

Return a list of services that match the query.

MIME Types

Request
Accept: application/vnd.apcera.service;version=1
Response
Content-Type: application/vnd.apcera.service;version=1

Request Parameters

Name Description Location Data Type Notes
fqn

Fully-qualified name of a service to return (service::/sandbox/admin::my-service, e.g.). If the matchPartialFQN query parameter is true then this parameter can specify just a namespace (job::/sandbox/admin, e.g.) and any services in that namespace are returned.

Query String
matchPartialFQN

If true all services in the namespace specified by the fqn query parameter are returned.

Query String (boolean)

Response

200 OK

Successful response.

POST /services

Creates a new service.

MIME Types

Request
Accept: application/vnd.apcera.service;version=1
Content-Type: application/vnd.apcera.service;version=1
Response
Content-Type: application/vnd.apcera.service;version=1

Request Parameters

None.

Request body

ServiceRequestObject object with required properties.

Response

200 OK

Successful response is the newly created Service object.

Response example
{
"created_at": "2017-07-24T23:51:36.614288429Z",
"created_by": "admin@apcera.me",
"description": "Encrypted APCFS service.",
"extended_status": {
},
"fqn": "service::/sandbox/admin::encrypted-file-service",
"name": "encrypted-file-service3",
"parameters": {
"encrypt": "true"
},
"provider_fqn": "provider::/apcera/providers::apcfs",
"status": "created",
"type": "nfs",
"uuid": "5f0726fe-8ed8-4e42-8f89-85d750dfa41a"
}

DELETE /services/{uuid}

Deletes the specified service.

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the service to delete.

Path String
Required

Response

200 OK

Successful response.

GET /services/{uuid}

Returns the specified Service.

MIME Types

Request
Accept: application/vnd.apcera.service;version=1
Response
Content-Type: application/vnd.apcera.service;version=1

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the service to return.

Path String
Required

Response

200 OK

Successful response contains the specified Service.

GET /stagingpipelines

Lists all StagingPipeline objects. To return a single staging pipeline specify its fully qualified name in the fqn query parameter.

MIME Types

Request
Accept: application/vnd.apcera.stagingpipeline;version=1
Response
Content-Type: application/vnd.apcera.stagingpipeline;version=1

Request Parameters

Name Description Location Data Type Notes
fqn

The fully qualified name the staging pipeline to retrieve.

Query String

Response

200 OK

Successful response.

Response example
[
{
"auto_id": 0,
"created_at": "2017-07-21T22:45:40.480069901Z",
"created_by": "stagehand@apcera.me",
"fqn": "stagpipe::/apcera::bash",
"name": "bash",
"stagers": [
{
"uuid": "fa3b2f63-d333-4f3c-840b-7ccb8ddfcedc"
}
],
"updated_at": "2017-07-21T22:45:40.480069901Z",
"updated_by": "",
"uuid": "46e9f3f0-721d-4865-9e68-e29d256dc97a",
"version_id": 1
},
{
"auto_id": 0,
"created_at": "2017-07-21T22:45:40.496048011Z",
"created_by": "stagehand@apcera.me",
"fqn": "stagpipe::/apcera::compiler",
"name": "compiler",
"stagers": [
{
"uuid": "9d74266a-aea2-483c-9dc9-3110ebc2896c"
}
],
"updated_at": "2017-07-21T22:45:40.496048011Z",
"updated_by": "",
"uuid": "9afcef47-cba0-4f55-87ae-8992b4328e23",
"version_id": 1
},
{
"auto_id": 0,
"created_at": "2017-07-21T22:45:40.50682302Z",
"created_by": "stagehand@apcera.me",
"fqn": "stagpipe::/apcera::go",
"name": "go",
"stagers": [
{
"uuid": "e68c7520-0474-4b10-9759-3c48a13adb96"
}
],
"updated_at": "2017-07-21T22:45:40.50682302Z",
"updated_by": "",
"uuid": "45b21a0f-5c4f-49f6-85be-e0b2a53360ed",
"version_id": 1
}
]

POST /stagingpipelines

Creates a new staging pipeline from one or more stager jobs.

MIME Types

Request
Accept: application/vnd.apcera.stagingpipeline;version=1
Content-Type: application/vnd.apcera.stagingpipeline;version=1
Response
Content-Type: application/vnd.apcera.stagingpipeline;version=1

Request Parameters

None.

Request body

StagingPipeline object with required properties.

Response

200 OK

Successful response.

DELETE /stagingpipelines/{uuid}

Deletes the specified StagingPipeline object.

MIME Types

Request
Accept: application/vnd.apcera.stagingpipeline;version=1
Response
Content-Type: application/vnd.apcera.stagingpipeline;version=1

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the staging pipeline to delete.

Path String
Required

Response

200 OK

Successful response.

GET /stagingpipelines/{uuid}

Returns the specified StagingPipeline object.

MIME Types

Request
Accept: application/vnd.apcera.stagingpipeline;version=1
Response
Content-Type: application/vnd.apcera.stagingpipeline;version=1

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the staging pipeline to retrieve.

Path String
Required

Response

200 OK

Successful response.

PUT /stagingpipelines/{uuid}

Updates the specified StagingPipeline with new properties.

MIME Types

Request
Accept: application/vnd.apcera.stagingpipeline;version=1
Content-Type: application/vnd.apcera.stagingpipeline;version=1
Response
Content-Type: application/vnd.apcera.stagingpipeline;version=1

Request Parameters

Name Description Location Data Type Notes
uuid

UUID of the staging pipeline to update.

Path String
Required

Request body

Response

200 OK

Successful response.

GET /tags

Lists all SchedulingTag objects on all instance managers in the cluster. Requires read privileges on the cluster realm. Note that each SchedulingTag object's type and source fields are blank as they only apply to jobs, not clusters.

MIME Types

Request
Accept: application/vnd.apcera.schedulingtag;version=1
Response
Content-Type: application/vnd.apcera.schedulingtag;version=1

Request Parameters

None.

Response

200 OK

Successful response.

Response example
[
{
"num_managers": 1,
"source": "",
"tag": "host-386f9335",
"type": ""
},
{
"num_managers": 1,
"source": "",
"tag": "host-697512f2",
"type": ""
},
{
"num_managers": 2,
"source": "",
"tag": "platform-aws",
"type": ""
}
]

GET /tasks/{uuid}

Used to track the progress of an asynchronous API operation, such call to POST /jobs/docker or POST /manifests. See Tracking progress of asynchronous API calls for more information.

MIME Types

Request
Accept: application/vnd.apcera.task;version=1
Response
Content-Type: application/vnd.apcera.task;version=1

Request Parameters

Name Description Location Data Type Notes
time

If specified, only task events that occurred after the specified time are returned. If not specified, all task events are returned.

Query String
uuid

UUID of task.

Path String
Required

Response

200 OK

Successful response.

POST /unbind

Removes a service binding from a job.

MIME Types

Request
Content-Type: application/vnd.apcera.unbind;version=1

Request Parameters

None.

Request body

UnbindParameterObject object with required properties.

Response

200 OK

Successful response.

POST /unlink

Removes a link between two jobs. The binding record is only removed from the from_job property of the request object.

MIME Types

Request
Content-Type: application/vnd.apcera.unlink;version=1

Request Parameters

None.

Request body

UnlinkParameterObject object with required properties.

Response

200 OK

Successful response.

GET /version

Returns cluster version number information and links to download a compatible APC binary from the cluster.

MIME Types

Request
Accept: application/vnd.apcera.versioninfo;version=1
Response
Content-Type: application/vnd.apcera.versioninfo;version=1

Request Parameters

None.

Response

200 OK

A successful response is a VersionInfo object.

Response example
{
"build_id": "1caa46a",
"build_number": "2.6.0",
"download_urls": {
"darwin_amd64": {
"sha256": "6b32794c2c719a6f0979fd18cc35d6eb4b87ab1c46c0ad78b74a563760af2a0a",
"size": 5675194,
"url": "https://api.example.com/apc/download/darwin_amd64/apc.gz"
},
"linux_amd64": {
"sha256": "a91854ba9479cbd380d016d11ab093789bdce030aecdce3a08b63f182b5768aa",
"size": 5726559,
"url": "https://api.example.com/apc/download/linux_amd64/apc.gz"
},
"windows_386": {
"sha256": "2c318a0880d7725c0ad81c602d5cb13f63ff1538b2d4f05b98787308f8a961c3",
"size": 5258467,
"url": "https://api.example.com/apc/download/windows_386/apc.zip"
},
"windows_amd64": {
"sha256": "027f891b0b60e06f74379cc0acb6b30de1eef10d96fb2e7c9ea06ef493817409",
"size": 5583772,
"url": "https://api.example.com/apc/download/windows_amd64/apc.zip"
}
},
"major": 2,
"minor": 6,
"patch": 0,
"version": "2.6.0"
}

Definitions

Definitions of objects used by the Apcera API.

AdminInfo

Cluster administrator information returned by GET /cluster/admin.

Name Description Type Notes
email

Email address of cluster administrator.

String
name

Name of cluster administrator.

String

APCDownloadURL

Contains information about an APC installer file download returned by GET /version.

Name Description Type Notes
sha256

256-byte hash of file.

String
size

Size of the file in bytes.

Integer
url

APC file download link.

String

APIError

Describes any non-200 HTTP response from a Apcera API call.

Name Description Type Notes
client_side

If true, the error was due to a client-side error (e.g., invalid data); otherwise, the error was due to a server-side error (e.g. a NATS timeout).

Boolean
code

HTTP status code returned to the user.

Integer
duplicate_key

If true, the resource that's being sought already exists.

Boolean
fatal

If true, the action was fatal and should not be retried.

Boolean
message

Error message string.

String
missing_claims

A list of missing policy claim(s) on policy denials.

String [ ]
policy_error

Describes policy error that caused the API error.

PolicyError
request_id

ID of the NATS message or HTTP request that generated the error.

String
request_invalid

If true, the request cannot be processed due to a conflict.

Boolean
requires_restart

If true, the targeted resource is in a state where the request cannot be fulfilled; for instance, a job in the started state may not have its resources changed.

Boolean
resource_missing

If true, the requested resource could not be located.

Boolean
retry

If true, the problem encountered was transient, and the same payload can be delivered again.

Boolean
token_invalid

If true, the requestor's token was invalid (e.g., due to a timeout.)

Boolean
try_again_in_ms

Specifies the amount of time in milliseconds that the client should wait before retrying the request.

Integer

AuditLogItem

Describes an audit log item returned by a call to GET /audit.

Name Description Type Notes
audit_payload

A JSON structure that contains details about the audit log item.

String
event_type

Event type.

String
event_type_int

Integer used as the index of an enumeration of human-readable event types (see event_type).

Integer
fqn

Fully-qualified name of the resource on which the auditable action was attempted.

String
localname

Local name of the resource on which the auditable action was attempted.

String
namespace

Namespace of the resource on which the auditable action was attempted.

String
on_behalf_of

Username on whose behalf the auditable action was attempted by principal_name.

String
principal_name

The actor (API Server or Health Manager, for example) or user that attempted the auditable action.

String
resource_type

The resource type on which the auditable action was attempted.

String
timestamp

UNIX timestamp that indicates when the event occurred.

Number (float)
uuid

Unique identifier for the audit log entry.

Example
{
"audit_payload": {
"patches": [
{
"oldvalue": "2017-03-27T23:47:37.164719871Z",
"op": "replace",
"path": "job/updated_at",
"value": "2017-03-27T23:47:51.530809553Z"
},
{
"oldvalue": 1,
"op": "replace",
"path": "job/version_id",
"value": 2
}
]
},
"event_type": "job.update",
"event_type_int": 2,
"fqn": "job::/sandbox/admin::api-docs",
"localname": "api-docs",
"namespace": "/sandbox/admin",
"on_behalf_of": "admin@apcera.com",
"principal_name": "api_server@apcera.me",
"resource_type": "job",
"timestamp": 1490658471,
"uuid": "ca47e5a0-1347-11e7-9dd5-06b7728d575f"
}

AutoscalingConfig

Object that defines a job's auto-scaling configuration.

Name Description Type Notes
max_instances

The maximum number of instances that the autoscaled job should have.

Integer
Minimum:
2
min_instances

The minimum number of instances that the autoscaled job should have.

Integer
Minimum:
1
observation_interval_secs

The interval on which the autoscaler will be sensing data and considering autoscaling.

Integer
Minimum:
10
Default:
10
rule

An autoscaling rule definition for a job.

AutoscalingRule
scale_timeout_secs

The interval on which the autoscaler will wait before timingout after a job scale action.

Integer
Minimum:
10
Default:
10
warmup_secs

The seconds to allow for new instances to be started before considering them for autoscaling.

Integer
Default:
0

AutoscalingRule

Defines an auto-scaling rule for a job. Specifies the method used to make auto-scaling decisions and its configuration parameters, as well as the performance metric upon which auto-scaling decisions should be made.

Name Description Type Notes
config

The configuration of an autoscaling rule method.

AutoscalingRuleConfig
metric

Name of the metric whose value will be monitored and upon which auto-scaling decisions are based. Valid values are any of the built-in metrics, or a custom metric name defined by the corresponding Job object's monitoring object.

String , valid values:
  • "cpu_per_second"
  • (default)
  • "requests_per_second"
  • "request_latency"
  • "<custom_metric_name>"
type

The type of auto-scaling method to use.

String , valid values:
  • "pid"
  • "threshold"

AutoscalingRuleConfig

Configuration for an auto-scaling rule for a job. This object includes fields for all available auto-scaler methods (currently, PID or threshold). Which fields you include in this object depend on the auto-scaling method (type) specified by the AutoscalingRule. Also, the default values for some fields depends on the observed performance metric specified in the AutoscalingRule.

Name Description Type Notes
kd

Derivative gain of a PID controller based autoscaled job.

Float
Default:
0
ki

Integral gain of a PID controller based autoscaled job.

Float
Default:
0.0013
kp

Proportional gain of a PID controller based autoscaled job.

Float
Default:
0.45
lower_threshold

Threshold value of the metric below which a scaling action should be triggered. The default value depends on the metric being observed, as follows:

  • cpu_per_second: 100 ms/s
  • requests_per_second: 1.0.
  • request_latency: 1.0
Integer
monitoring_window_secs

Number of seconds during which the value of the metric must be beyond the same threshold before an action gets triggered.

Integer
Default:
0
scale_down_delta

Magnitude of a scale-down action.

Integer
Default:
1
scale_up_delta

Magnitude of a scale-up action.

Integer
Default:
1
setpoint

Target value of the metric to maintain using the PID controller scaling method. The default value depends on the metric being observed, as follows:

  • cpu_per_second: 100 ms/s
  • requests_per_second: 1.0.
  • request_latency: 1.0
Float
upper_threshold

Threshold value of the metric above which a scaling action should be triggered.

Integer

Binding

Describes a job link or service binding on a job.

Name Description Type Notes
env_var

List of environment variables generated for the binding.

String [ ]
fqn

The binding's fully-qualified name.

String
job_fqn

Fully-qualified name of the job that is bound to another job or service.

String
name

The base name of the binding.

String
parameters

A map of custom binding parameter names to their values.

Object
provider_fqn

Fully-qualified name of the provider used to create the service to which the source job is bound. Only relevant for job-to-service bindings.

String
service_fqn

Fully-qualified name of a the service to which the source job is bound. Only relevant for for job-to-service bindings.

String
target_job_bound_ip

IP address where the connection to the target job should be exposed.

String
target_job_bound_port

Port that the target job should be exposed at.

String
target_job_fqn

Fully-qualified name of the job to which the source job wants to bind (input only).

String
target_job_port

Port on the target job that the source job wants to bind to.

String
target_job_uuid

UUID of the job to which the source job is bound (output only).

String
uuid

UUID of the binding.

CertificateMetadata

Name Description Type Notes
issuer_cn

Certificate's Issuer's Common Name.

String
not_after

Certificate expiration. Date after which certificate is no longer valid.

String (date-time)
not_before

Date before which certificate is not valid.

String (date-time)
sans_names

Certificate's Subject Alternative Names.

String [ ]
serial_num

Certificate serial number.

String
subject_cn

Certificate's Subject Common Name.

String

CreateDockerJobRequest

Object passed in request body to POST /jobs/docker.

Name Description Type Notes
allow_egress

If true, the job is allowed outbound network connectivity.

Boolean
env

Map of environment variable names to values to assign to the job.

Object
exposed_ports

An array of ports exposed on job instances.

Integer [ ]
group

Group to run Docker image as (default: picked by Apcera).

String
hard_scheduling_tags

List of hard scheduling tags. See Hard Tags for more information.

Object
ignore_volumes

If true, volumes specified in the Docker image spec are ignored and no data will be persisted. If false or not specified, and the Docker image specifies volumes, then you must supply a provider FQN in the request object's volume_provider_fqn property.

Boolean
image_url

Docker image URL.

String
Required
interactive

If true, the start command is removed from the job definition. The start command string is saved to the DOCKER_START_COMMAND environment variable on the job's environment.

Boolean
job_fqn

The fully-qualified name of the job to create from the Docker image.

String
pull

If true the platform pulls the latest Docker image manifest from the image repository rather than using its cached version of the manifest (false). Setting to true ensures that any updates to the image layers will be downloaded. See Docker image caching for more information.

Boolean
resources

Compute resources to reserve for the application.

Resource
restart

Restart configuration for the job.

RestartConfig
routes

A map of routes to the ports where the routes are available.

Object
soft_scheduling_tags

List of soft scheduling tags. See Soft Tags for more information.

Object
start

If true the job is started after its created. Default is false.

Boolean
start_command

The command used to start the process, specified as an array. The first element in the array is the command/binary to execute, and subsequent array elements are command arguments. The expanded command string is passed directly to exec() without shell or template interpretation.

String [ ]
stop_command

The command used to stop the process, specified as an array. The first element in the array is the command/binary to execute, and subsequent array elements are command arguments. The expanded command string is passed directly to exec() without shell or template interpretation.

String [ ]
user

User to run Docker image as. Defaults to user in the Docker image configuration, or 'root' if image doesn't have a user configured.

String
volume_provider_fqn

Volume provider's fully-qualified name. Required if ignore_volumes is not set to true.

String
volumes

A list of volumes used by the Docker image for persistence.

String [ ]
Example
{
"image_url": "hello-world",
"job_fqn": "job::/sandbox/admin::hello-world",
"state": "started"
}

CreateDockerPackageRequest

Object passed in request body to POST /packages/docker.

Name Description Type Notes
image_url

URL of the Docker image from which the package will be created.

String
Required
package_fqn

FQN of the package to create.

String
Required
Example
{
"image_url": "hello-world",
"package_fqn": "package::/sandbox/admin::hello-world"
}

CreateProviderRequest

Object sent in request to POST /providers.

Name Description Type Notes
backing_job_fqn

For providers running as a job within the Apcera cluster, specifies the backing job's FQN.

String
backing_job_port

For providers running as a job within the Apcera cluster, specifies the port used to connect to the backing job.

String
description

Provider description.

String
fqn

Provider's fully qualified name.

String
Required
name

Provider's local name.

String
parameters

A map of parameter names to values used to configure the provider. The map must contain a parameter named "url" that contains administrative connection information for the provider, including credentials (for example, "postgres://admin:password@example.com:5432"). The map may contain any number of additional parameters specific to the service type.

Object
Required
rootcerts

Base64-encoded contents of PEM file that contains the root certificate to use with this provider. This is mainly useful when registering an external MySQL or Postgres provider that requires authentication. See Registering external providers.

Object
type

Provider's type (e.g. "mysql", "postgres"). Required to determine the service gateway with which to register the provider.

String
Required

Dependency

Describes a package dependency.

Name Description Type Notes
name

A string that describes the resource that can be depended on (e.g., "java", "apache-2.2").

String
type

The type of dependency.

String , valid values:
  • "file"
  • "package"
  • "runtime"
  • "os"

Drain

Describes a log drain attached to a job.

Name Description Type Notes
conf

Log drain configuration object.

DrainConfig
max_size

Maximum bytes per log line to send. Defaults to 2048 bytes.

Integer
url

A syslog URL in the form of syslog://hostname:port.

String
Required
uuid

UUID of the drain object.

UUID Read-only

DrainConfig

Configuration object for a log drain.

Name Description Type Notes
priority

The configured syslog priority.

Integer
protocol

The default syslog protocol to dial over. Defaults to TCP.

String , valid values:
  • "tcp"

ExtendedStatus

Represents optional status information provided by a service gateway about the progress of the creation of a new provider.

Name Description Type Notes
current_step

Current step of the provider creation process.

Integer
percent_complete

Percentage complete of operation.

Integer
time_remaining

An estimate of the time remaining to complete creation of the provider.

Integer
total_steps

Total number of steps to complete the operation.

Integer

FileListing

Describes a file listing returned by GET /jobs/{uuid}/files/{path}.

Name Description Type Notes
name

Name of the file or directory in the target path. Directory names are suffixed by a trailing forward slash (for example, app/).

String
size

For file resources, the size of the file in bytes. For directories, this field is not calculated.

Number (float)

Info

Contains basic information about an Apcera cluster returned by GET /info.

Name Description Type Notes
cluster_domain

Cluster domain.

String
name

API server name. Currently contains "Continuum".

String
url

URL of Apcera API Server (for example, api.try.apcera.net).

String

Instance

Contains information about a running job instance returned by a call to GET /jobs/{uuid}/instances.

Name Description Type Notes
announced_routes

Indicates whether the routes for this instance have been announced.

Boolean
created_time

UNIX timestamp for when instance was created.

Number (float)
exit_code

Exit code of the main processes; should only be checked if exited is true.

Integer
exited

Set to true if the instance started and its main process managed to exit.

Boolean
failed

Set to true if the instance has failed in some way.

Boolean
host

Name of the host the instance is running on.

String
instance_manager_uuid

UUID of the instance manager running the instance.

job_version_id

The sequence number of the job the instance is running.

Integer (int64)
state

Instance's state as reported by the health manager.

String , valid values:
  • "FIRST_RUNNING"
  • "NEW"
  • "REMOVED"
  • "RUNNING"
  • "SETUP"
  • "STARTING"
  • "STARTING_WAIT"
  • "STOPPING"
  • "STOPPING_WAIT"
  • "TEARDOWN"
  • "UPDATING"
uuid

The instance's unique identifier.

InstanceManagerStatus

Describes an instance manager returned by call to GET /instance_managers or to GET /instance_managers/{uuid}.

Name Description Type Notes
datacenter

Tag that specifies the data center the instance manager is running in.

String
hostname

Instance manager's host name.

String
num_instances

The number of job instances being managed by the instance manager.

Integer
ResourcesProvisioned

Compute resources provisioned for all jobs running on the instance manager.

Resource
ResourcesTotal

Total compute resources available to the instance manager.

Resource
start_time

Date and time that instance manager was started.

String (date-time)
system_tags

A list of system tags assigned to the instance manager.

String [ ]
tags

A list of user tags assigned to the instance manager.

String [ ]
uptime

Time in nanoseconds that the instance manager has been up.

Number
uuid

Instance manager's unique identifier.

InstanceState

State of an instance in its life-cycle.

Name Description Type Notes
FIRST_RUNNING

Number of instances where the job was started and is about to move into the RUNNING state.

Integer
NEW

Number of instances in the NEW state.

Integer
REMOVED

Number of instances that are no longer consuming resources and have no remaining configuration on the system.

Integer
RUNNING

Number of instances that are running.

Integer
SETUP

Number of instances in which packages are being installed, networking initialized, etc.

Integer
STARTING

Number of instances whose processes have been started, but have not been verified to be running.

Integer
STARTING_WAIT

Number of instances that are waiting for dependent jobs to become ready.

Integer
STOPPING

Number of instances that are in the process of having their processes shutdown.

Integer
STOPPING_WAIT

Number of instances that are being stopped, but have jobs depending on it. In this case the other jobs must first transition past the STOPPING state before this instance can be stopped.

Integer
TEARDOWN

Number of instances whose user-defined processes have been killed, and the instance is being removed from cluster resources.

Integer
UPDATING

Number of instances that are in a state that allows the instance to update various properties of the container.

Integer

InstanceStatus

Provides status information for a running job instance returned by a call to GET /instance_managers/{uuid}/instances. This is a simplified version of an Instance object returned by GET /jobs/{uuid}/instances.

Name Description Type Notes
job_fqn

FQN of the job used to create the instance.

String
job_uuid

UUID of the job used to create the instance.

String
resources

Compute resources provisioned for the instance.

Resource
start_time

Date/time that instance was started.

String (date-time)
state

Instance state.

InstanceState
uptime

Duration that this instance has been alive, in nanoseconds.

Integer (int64)
uuid

UUID of the job instance.

String

Job

Describes all properties of a job within the platform, including dependent packages, job links, service bindings, and virtual networks.

Name Description Type Notes
autoscaling

Object that defines a job's auto-scaling behavior.

AutoscalingConfig
bindings

A map of service bindings FQNs to Binding objects.

Object
created_at

Time at which the job was created.

String (date-time)
Read-only
created_by

The principal name of user who created the job.

String
Read-only
fqn

Job's fully-qualified name.

String
Required
hard_scheduling_tags

Deprecated, use scheduling_tags. List of hard scheduling tags. See Hard Tags for more information.

Object
health

Contains information about the health of the job's running instances. Only present in responses to GET /jobs/health or GET /jobs if the health query parameter is set to true. If empty, then job instance health has not been retrieved from the health manager yet.

JobHealth
logs

An array of logs the job will be producing that should be collected for aggregation or streaming.

Log [ ]
monitoring

A map of custom metric names to MonitoringRule objects used in job auto-scaling.

Object
name

Name of the job.

String
network_ref

Contains information about virtual networks this job belongs to.

JobNetworkReference
num_instances

The desired number of instances (containers) of the job you want to run.

Integer
Required
packages

List of the job's dependent packages, including both user-provided packages and package dependencies calculated by the package manager.

PackageInfo [ ]
ports

An array of ports associated with the job.

Port [ ]
processes

A map of arbitrary process names to Process objects.

Object
resources

The compute resources assigned to the job.

Resource
restart

The job's restart configuration.

RestartConfig
rollout

Configuration related to rolling updates of the job.

RolloutConfig
scheduling_tags

List of scheduling tags assigned to the job.

SchedulingTag [ ]
soft_scheduling_tags

Deprecated, use scheduling_tags. List of soft scheduling tags. See Soft Tags for more information.

Object
state

Job's state in its life-cycle.

String , valid values:
  • "invalid"
  • "unknown"
  • "created"
  • "errored"
  • "staging"
  • "staging_failed"
  • "ready"
  • "started"
  • "stopped"
  • "finished"
Read-only
sticky_session_cookies

A list of session cookie names that the HTTP router should recognize and provide instance stickiness for.

String [ ]
tags

Map of tag names to values.

Object
updated_at

Time at which the job was most recently updated.

String (date-time)
Read-only
updated_by

The principal name of the last user to update the job.

String
Read-only
uuid

The job's unique identifier.

UUID
version_id

An auto-incremented number that indicates the revision of the object.

Integer
weight

A job's weight is used to route requests to this job relative to other job that have the same routes. See Sharing Routes and Route Weights.

Integer
Example
{
"aggregate_network_routes": null,
"created_at": "2017-04-03T22:36:03.942833577Z",
"created_by": "admin",
"fqn": "job::/sandbox/admin::app4",
"logs": [
{
"channel": "job.$JOB_UUID.$INSTANCE_UUID.stdout",
"file": "/logs/stdout.*.log"
},
{
"channel": "job.$JOB_UUID.$INSTANCE_UUID.stderr",
"file": "/logs/stderr.*.log"
}
],
"name": "app4",
"network_ref": null,
"num_instances": 1,
"packages": [
{
"source": "user",
"state": "unknown",
"uuid": "ee91ab6c-3879-493d-94db-d9012c109905"
},
{
"source": "system",
"state": "ready",
"uuid": "03279c73-9d31-4940-91f0-288cbb44df74"
}
],
"ports": [
{
"number": 0,
"optional": false,
"routes": [
{
"auto_provision": true,
"endpoint": "app4.example.com",
"https_only": false,
"type": "http",
"weight": 0
}
]
}
],
"processes": {
"app": {
"start_command": "",
"start_command_raw": [
],
"start_command_timeout": 30,
"stop_command": "",
"stop_command_raw": [
],
"stop_timeout": 5
}
},
"resources": {
"cpu": 0,
"disk": 1073741824,
"memory": 268435456,
"netmax": 0,
"network": 5000000
},
"restart": {
"restart_mode": "always"
},
"rollout": {
"errored_state_window": 0,
"flapping_minimum_restarts": 3,
"flapping_percent": 0.5,
"flapping_window": 300,
"force_stop_old_instances_after": 120
},
"state": "started",
"tags": {
"app": "app4"
},
"updated_at": "2017-04-03T22:37:23.022240787Z",
"updated_by": "admin",
"uuid": "a6c6113e-e6fa-4bdc-96f5-26bb7534ab85",
"version_id": 2
}

JobHealth

Represents job health information returned by GET /jobs/health or GET /jobs when the health query parameter is true.

Name Description Type Notes
flapping

Indicates if job is in a flapping state (true) or not (false).

Boolean
instance_state_count

Map of instance states to the number of instances in that state, as reported by the health manager.

Object
score

Score is the ratio of running instances to configured instances, capped between 0 and 1.

Integer
uuid

UUID of the job.

Boolean

JobNetworkReference

Contains information about a virtual network that belongs to a job.

Name Description Type Notes
uuid

UUID of the virtual network the job belongs to.

String

Log

Describes a log file that this job will be producing that should be collected for aggregation or streaming.

Name Description Type Notes
channel

The name of the channel that the log should be published on.

String
file

The path to the log file within the job's container that should be collected.

String
jobid

UUID of the job generating the log.

String

Manifest

Describes a JSON-formatted multi-resource manifest. See Using Multi-Resource Manifests for a description of the manifest schema.

ManifestResponse

Represents a successful response to POST /manifests or POST /manifests/expansion. Some fields are only populated in response to calling POST /manifests/expansion.

Name Description Type Notes
expanded_json

Contains the expanded manifest in raw JSON format from a call to POST /manifests/expansion.

String
expanded_manifest

Contains the expanded multi-resource manifest from a call to POST /manifests/expansion.

String (JSON)
location

The URL of the Task resource that indicates the status of the manifest execution process running on the API Server. A Task contains one or more TaskEvent objects that contain details about each step of the asynchronous process. Clients can either poll this endpoint over HTTP or use it to stream TaskEvent objects over WebSockets.

String
warnings

A comma-delimited list of warnings that resulted from a call to POST /manifests/expansion.

String

MappedJob

Name Description Type Notes
job_uuid

Unique identifier of the job attached to the route.

port

Exposed port on the job.

Integer (int32)
weight

Weight specific to the route.

Number (float)

MonitoringRule

Defines a monitoring rule for a custom metric used to auto-scale a job.

Name Description Type Notes
config

A custom monitoring rule configuration.

MonitoringRuleConfig
type

The type of monitoring rule. Currently, the only supported type is http_metric.

String , valid values:
  • "http_metric"

MonitoringRuleConfig

A custom metric monitoring rule configuration.

Name Description Type Notes
url

An HTTP endpoint that returns a string representation of a float value used to make auto-scaling decisions.

String

Namespace

Name Description Type Notes
namespace

A namespace.

String

Package

Describes a package. May be an application package, a runtime, or an operating system.

Name Description Type Notes
created_at

The date and time when the package was created.

String (date-time)
created_by

Principal name of the user who created the package.

String
dependencies

List of package dependencies that must be met for the package to be used. A dependency expresses a requirement that a package has on an other package.

Dependency [ ]
docker_image_id

A hash digest of the Docker image used to create the package.

String
Read-only
docker_origin

For packages created from a Docker image, contains the URL of the source Docker image.

String
Read-only
environment

A map of environment variable names to values. The environment variables are added to any process that uses the package.

Object
error_message

Error encountered during an asynchronous operation on the package. An example is a failure encountered during instance snapshot; the ErrorMessage field on the created snapshot package would contain more information.

String
fqn

Package's fully-qualified name.

String
name

Package name.

String
provides

List of packages that this package provides for other packages to use. A "provide" expresses a named resource that other packages or jobs can add as a dependency.

Provide [ ]
resource

Deprecated. Use resources array. An object that describes the package's associated binary resource.

PackageResource
resources

A list of binary package resources associated with this package.

PackageResource [ ]
staging_pipeline

The UUID of the staging pipeline used to stage this package into a runnable state.

String
staging_pipeline_fqn

The fully-qualified name of the staging pipeline used to stage the package.

String
state

Package state.

String , valid values:
  • "uploading"
  • "staging"
  • "failed"
  • "ready"
  • "deleted"
  • "unknown"
Read-only
tags

Map of tags by tag name.

Object
updated_at

The date and time when the package was most recently updated.

String (date-time)
updated_by

Principal name of the last user to update the package.

String
uuid

The package's unique identifier.

String
version_id

Package's auto-incremented version number.

Integer (int64)

PackageDependsRequest

Request object for a call to POST /packages/dependencies to resolve package dependencies from a package name and type.

Name Description Type Notes
dependencies

A list of package dependencies to resolve.

Dependency [ ]
job_target

Namespace in which dependencies will be resolved (e.g. the namespace of a job that is being staged, the namespace of the user requesting the resolution).

String

PackageInfo

Contains basic information about a package.

Name Description Type Notes
source

The source of the package, whether it was provided by the user or calculated by the Package Manager.

String , valid values:
  • "user"
  • "system"
state

Represents the availability of the package.

String , valid values:
  • "unknown"
  • "uploading"
  • "staging"
  • "failed"
  • "ready"
  • "deleted"
uuid

UUID of the package.

String

PackageResource

Describes a binary resource associated with a package.

Name Description Type Notes
digest

A SHA-1, SHA-256, SHA-384, or SHA-512 hash of a binary package resource being uploaded, prefixed by sha1:, sha256:, sha384:, or sha512:, depending on the hash function used (for example: sha1:3c650b19716f3fe6ca293fbf78795f45ba684ea6).

String
length

The length of the binary resource in bytes. The value must match the length specified when creating the package with POST /packages.

Integer
sha1

Deprecated. Duplicates the digest field for resources encrypted with the SHA-1 algorithm.

String
uuid

Package resource's unique ID.

UUID

PolicyError

Represents a policy error referenced by an APIError response object's policy_error field. Indicates that one or more policy violations occurred that prevented the API call from succeeding.

Name Description Type Notes
errors

An array of specific policy errors that occurred.

String [ ]
job

The job which the policy error applies to.

Job
job_changed

If true, the policy error was the result of changes to a job.

Boolean
repairable

If true, the error is repairable.

Boolean

Port

Represents a port exposed on a job.

Name Description Type Notes
number

The port exposed for connectivity on the job.

Integer
optional

A value of true indicates that the instance manager (IM) should NOT attempt to verify that connectivity has been established for this port; if false, no such verification occurs.

Boolean
routes

An array of URLs to map to the port.

Route [ ]

Process

Describes a process used to start a job.

Name Description Type Notes
environment

An optional list of environment values to attach to the process within the job.

Object
group

Name of the group used to run the process within a container. An empty string lets the the instance manager choose a group.

String
heavy

Start the process in "heavy" mode: giving it pid 1. Only one process within the job can set this flag to true.

Boolean
start_command

The command used to start the process within the container's isolation context.

String
start_command_raw

The command used to start the process, specified as an array. The first element in the array is the command/binary to execute, and subsequent array elements are command arguments. The expanded command string is passed directly to exec() without shell or template interpretation. If start_command_raw is provided then start_command, if specified, is ignored. This property is typically used with exact processes that have an extremely well-known start command.

String [ ]
start_command_timeout

The number of seconds that the system will wait for startup to complete. This includes the time that it will take for ports to become available.

Integer
stop_command

The command used to stop the process within the container's isolation context. If not defined, OS-level signals (like TERM) may be used to shut down the process.

String
stop_command_raw

The command used to stop the process, specified as an array. The first element in the array is the command/binary to execute, and subsequent array elements are command arguments. The expanded command string is passed directly to exec() without shell or template interpretation. If stop_command_raw is provided then stop_command, if specified, is ignored. This property is typically used with exact processes that have an extremely well-known start command.

String [ ]
stop_timeout

The number of seconds to give the process after stop_command has been run before forcing the command to shutdown via OS-level signals, such as TERM. If no stop_command is provided for the process, OS-level signals (like TERM) may be used to terminate the process.

Integer
user

Name of the user used to run the process within a container. An empty string lets the the instance manager choose a user.

String

Provide

A "provide" expresses a named and typed resource that other packages or jobs can add as a dependency.

Name Description Type Notes
name

A string that describes the resource being provided. A name could be java or apache-2.2.

String
type

The type of provide. Possible values are file, package, runtime, and os.

String , valid values:
  • "file"
  • "package"
  • "runtime"
  • "os"

ProviderInfo

Describes a service provider.

Name Description Type Notes
backing_job_fqn

For providers running as a job within the Apcera cluster, specifies the backing job's FQN.

String
backing_job_port

For providers running as a job within the Apcera cluster, specifies the port used to connect to the backing job.

String
description

Provider description.

String
extended_status

Optional status information about the progress of the creation of the provider.

ExtendedStatus
fqn

Provider's fully qualified name.

String
Required
gateway_id

ID used internally by the service gateway to identify the provider.

String
Read-only
name

Provider's local name.

String
parameters

A map of parameter names to values used to configure the provider. The map must contain a parameter named "url" that contains administrative connection information for the provider, including credentials (for example, "postgres://admin:password@example.com:5432"). The map may contain any number of additional parameters specific to the service type.

Object
Required
state

Provider's state in Base64-encoded format.

String
status

Indicates status of the creation of the provider.

Object
type

Provider's type (e.g. "mysql", "postgres"). Required to determine the service gateway with which to register the provider.

String
Required
uuid

Provider UUID.

String

Resource

Describes compute and network resources.

Name Description Type Notes
cpu

Milliseconds of CPU time per second of physical time allocated to the job. May be greater than 1000ms/second in cases where time is across multiple cores.

Integer (int64)
disk

Amount of disk space allocated to the job, in MB.

Integer (int64)
memory

Memory allocated to job, in MB.

Integer (int64)
netmax

Maximum amount of network throughput (ceiling) allowed, in Mbps.

Integer (int64)
network

Amount of network throughput (floor) allocated to the job, in Mbps.

Integer (int64)
Example
{
"cpu": 200,
"disk": 1073741824,
"memory": 268435456,
"netmax": 0,
"network": 5000000
}

RestartConfig

Configuration related to restarting the job.

Name Description Type Notes
maximum_attempts

The maximum number of restart attempts per instance, applies to always and failure restart modes. If set to 0 restarts are not limited.

Integer
restart_mode

The restart mode to use. Valid values are always (always restart), no (never restart), and failure (only restart on application failure).

String , valid values:
  • "always"
  • "no"
  • "failure"

RolloutConfig

Configuration related to rolling updates of the job.

Name Description Type Notes
errored_state_window

The number of seconds a job should be cycling between flapping states before being considered in an errored state and stop attempting any restarts.

Integer
Minimum:
10800
Maximum:
604800
Default:
259200
flapping_minimum_restarts

The minimum number of tasks that must have failed in order to trigger a flapping state.

Integer
Minimum:
3
Maximum:
30
Default:
3
flapping_percent

The percentage of instances that must have restarted in a the specified flapping_window for flapping to kick in.

Number (float)
Minimum:
0.01
Maximum:
10
Default:
0.5
flapping_window

The number of seconds over which the job's flapping window operates.

Integer
Minimum:
300
Maximum:
600
Default:
300
force_stop_old_instances_after

If this field is non-zero then it represents the number of seconds an old version of a job is allowed to exist in the cluster before being stopped. If this is zero then no fixed length is established and updates will be applied by starting a new version and then only when that instance is running will the old instance be killed.

Integer
Maximum:
600
Default:
120

Route

Name Description Type Notes
auto_provision

Read-only property that specifies if the route's endpoint was auto-provisioned by Apcera when it was created (true) or if it was specified explicitly.

Boolean
Read-only
created_at

Time at which the route was created.

String (date-time)
created_by

Principal name of the user who created the route.

String
endpoint

The URI where the traffic should being routed to. For HTTP routes, the value should contain the route's host and path; for TCP routes, the value should take the form of "ip:port".

String
https_only

Specifies if HTTPS should be enforced on the route. By default, clients can access the route using either HTTP or HTTPS. See Enforcing HTTPS on Routes.

Boolean
mapped_jobs

List of jobs for which the route is mapped.

MappedJob [ ]
type

The type of route. Valid values are http or tcp.

String
updated_by

Principal name of the user who created the route.

String
uuid

Route's unique identifier.

version_id

An auto-incremented number that indicates the revision of the object.

Integer (int64)
weight

A value between 0 and 1 that specifies the route's weight, which is used to balance incoming traffic across apps that share the route. Weights are not on a specific scale; weights of all routes for a given job are normalized.

Number (float)

Rule

Name Description Type Notes
action

The type of action to take when the rule is triggered. Can either by 'hook' or 'notification'.

String
created_at

UNIX timestamp when event rule was created.

Number (float)
created_by

Principal name of user who created the event rule.

String
fqn

The rule's fully-qualified name against which policy may be enforced.

String
job

FQN of the job to enforce the rule against.

String
provider

FQN of the provider to enforce this rule against. In only provider is populated for this rule, then all semantic pipelines consuming a provider matching this FQN will have the rule enforced against them.

String
service

FQN of the service to enforce this rule against. If only service is populated for this rule, then all semantic pipelines consuming a service matching this FQN will have the rule enforced against them.

String
type

Type depends upon specified action of event rule, and can specify the timing of the hook firing.

String
version_id

Rule's auto-incremented version number.

Integer

Runtime

Name Description Type Notes
patterns

An array of file names or patterns used to select the appropriate runtime.

String [ ]
runtime

Identifies the local name of the staging pipeline to use to stage the file (for example, "bash", or "perl").

String

SchedulingTag

A SchedulingTag describes a scheduling constraint on a job. Each instance manager in a cluster has a set of tags that are compared against the scheduling tags on a job when attempting to start an instance of that job. The tag field contains the string that should be present among an instance manager's tags. The type field must be set to either hard or soft, signifying that the constraint is either a hard requirement or an optional constraint, respectively. The source field is either user or policy and identifies whether the tag was added by the user or derived from policy. Users are not allowed to add tags with source policy.

Name Description Type Notes
num_managers

The number of instance managers that have this tag.

Integer
source

Specifies if the tag was added by a user (API call) or derived from policy. Users are not allowed to add tags with a source of policy.

String , valid values:
  • "user"
  • "policy"
tag

The scheduling tag that should be present among an instance manager's tags.

String
type

Identifies the type of scheduling constraint, hard or soft.

String , valid values:
  • "hard"
  • "soft"

Secret

Name Description Type Notes
certificate_metadata

List of certificate-metadata derived from the certificates defined in the secret (PEM file).

CertificateMetadata [ ]
created_at

Unix timestamp when the secret was created.

Number
created_by

Principal name of the user who created the secret.

String
desc

Description of the secret.

String
fqn

Fully qualifed name of the secret.

String
type

Designates the type of the secret. Can be 'certificate', 'certificate_and_private_key', 'private_key' or 'secret'

String
updated_at

Unix timestamp when the secret was last updated.

Number
updated_by

Principal name of the last user to update the secret.

String
version_id

An auto-incremented number that indicates the revision of the object.

Integer (int64)

SecretCreateRequest

Name Description Type Notes
data

PEM data of the secret. This is a Base64 encoded value.

String (base64)
desc

Description of the secret.

String
fqn

Fully-qualified name of the secret being imported.

String
password

Password of a password-protected key(s) in the uploaded PEM file. This is a Base64 encoded value

String (base64)
type

Designates the type of the secret. Can be 'certificate', 'certificate_and_private_key', 'private_key' or 'secret'

String
version_id

An auto-incremented number that indicates the revision of the object.

Integer (int64)

SecretInstall

Name Description Type Notes
certificate

Fully qualifed name of certificate to be installed on the router.

String
domain

The domain for which the certificate is to be bound on the router.

String
private_key

Fully qualified name of the private-key to be installed on the router.

String
version_id

An auto-incremented number that indicates the revision of the object.

Integer (int64)

SemiPipeRule

Name Description Type Notes
action

Describes the commands that will trigger the hook or notification and the URI to receive the hook or notification.

SemiPipeRuleAction
created_at

Date-time when rule was created.

String (date-time)
created_by

User that created the rule.

String
job

Specific job that rule applies to.

String
name

Rule name.

String
provider

Provider used to provision the service, if any.

String
service

FQN of service to which the rule applies.

String
type

Rule type.

Integer
uuid

Rule's unique identifier.

String

SemiPipeRuleAction

Name Description Type Notes
commands

Commands that will trigger the hook or notification.

String [ ]
inline

If no URL is given, you can specify an action directly. URL and action cannot be specified at the same time. Action can be 'allow' or 'deny'.

String
uri

URL to receive the hook or notification request. Required for notifications, but optional for hooks.

String

Service

Describes a service within the platform.

Name Description Type Notes
created_at

UNIX timestamp when service was created.

Number
created_by

Principal name of the user who created the service.

String
description

A human-readable description of the service.

String
fqn

Service's fully-qualified name.

String
parameters

A map of service parameter names to values.

Object
provider_fqn

Fully-qualified name of provider used to create service.

String
type

A service type ('mysql', 'postgres', 'mongodb', etc.) that corresponds to a service gateway of that type.

String
uuid

Service's unique identifer

String

ServiceRequestObject

Object used to create a new service.

Name Description Type Notes
description

A description of the service.

String
fqn

The service's fully-qualified name.

String
Required
name

A human-readable description of the service.

String
parameters

A map of service parameter names to values.

Object
provider_fqn

The fully-qualified name of provider used to create service.

String
Required
type

A service type ('mysql', 'postgres', 'mongodb', etc.) that corresponds to a service gateway of that type.

String
Required

StagerJob

Identifies a job used as a stager in a StagingPipeline.

Name Description Type Notes
uuid

UUID of the job to use as a stager.

String

StagingPipeline

Name Description Type Notes
auto_id

The automatic ID assigned to the object.

Integer
created_at

The date and time when the staging pipeline was created.

String (date-time)
created_by

Principal name of the user who created the staging pipeline.

String
fqn

Staging pipeline's FQN.

String
Required
name

Staging pipeline's local name.

String
Required
stagers

A list of objects that identify the stager jobs that belong to the staging pipeline.

StagerJob [ ] Required
updated_at

The date and time when the staging pipeline was most recently updated.

String (date-time)
updated_by

Principal name of the user who last updated the staging pipeline.

String
uuid

Staging pipeline's unique identifier.

String
version_id

Staging pipeline's auto-incremented version number.

String

SubnetInfo

Name Description Type Notes
Subnet

The subnet assigned to a virtual network in CIDR notation (192.168.1.0/24, for example).

String

SubTask

Describes a sub-task operation in a running Task.

Name Description Type Notes
index

The index of this subtask among all the task's subtasks.

Integer
name

A human-readable description of this subtask.

String
progress

Represents the progress of this subtask.

TaskProgress
total

The total number of subtasks in the current stage.

Integer

Task

Represents a long-running task on the API server returned by the GET /tasks/{uuid} endpoint...A Task is created in response to some API calls (such as POST /jobs/docker) that return the URL of the corresponding Task object. Clients poll this URL until the response object's state is set to "complete" (indicating a successful completion of the task) or "stopped" (indicating a non-successful completion).

Name Description Type Notes
errored

Describes the error for a Task that has encountered an error.

String
events

List of all TaskEvents that have been published for this particular task.

TaskEvent [ ]
state

The Task's current state.

String , valid values:
  • "running"
  • "stopped"
  • "complete"
time_completed

Indicates the time when the task completed. Stored as a UNIX timestamp with nanosecond precision.

Integer (int64)
time_started

Indicates the time when the task was started. Stored as a UNIX timestamp with nanosecond precision.

Integer (int64)
uuid

The task's unique identifier.

String

TaskEvent

Describes an individual task event within a parent Task.

Name Description Type Notes
payload

Extra information about the TaskEvent.

Object
stage

A logical grouping of subtasks. A stage could be "Creating Job" or "Downloading Packages".

String
subtask

Describes a subtask and its progress.

SubTask
tags

An list of tags that provide a hint about what is being tracked.

String [ ]
task_event_type

The type of message this TaskEvent contains.

String , valid values:
  • "event"
  • "error"
  • "eos"
  • "disconnect"
  • "cancel"
task_uuid

UUID of the Task that stores this event.

String
thread

Represents a logically independent procedure within a Task. For instance, a thread could be "job1" or "job2", or "Link job1 and job2".

String
time

Time in UNIX nanoseconds immediately before the TaskEvent gets announced on NATS.

Integer (int64)
uuid

UUID of the Task that stores this event.

TaskProgress

Indicates the progress of a SubTask within a Task.

Name Description Type Notes
current

Current progress.

Number (int64)
progress

Total amount of work to be done.

Number (int64)

TaskResponse

Represents the response to an API call that starts a long-running asynchronous process, such as POST /jobs/docker or POST /jobs/manifest. See Tracking progress of asynchronous API calls for more information.

Name Description Type Notes
location

The URL of the Task resource that indicates the status of the manifest execution. A Task contains one or more TaskEvent objects that contain details about each step of the asynchronous process. Clients can either poll this endpoint over HTTP or use it to stream TaskEvents using WebSockets.

String

UnbindParameterObject

Object passed in request body to POST /unlink endpoint.

Name Description Type Notes
force

If true, forces the binding to be removed and ignores errors from the backing service. Can be useful if the service is no longer available or is experiencing failures.

Boolean
job

Fully-qualified name of the job to unbind from the service specified by the service parameter.

String
service

Fully-qualified name of the service to unbind from the job specified by the job parameter.

String

UnlinkParameterObject

Object passed in request body to POST /unlink endpoint.

Name Description Type Notes
from_job

FQN of the job being linked from.

String
port

The port on the target job to link to.

Integer
to_job

FQN of the target job.

String

UUID

A unique resource identifier.

VersionInfo

Name Description Type Notes
build_id

Cluster's build ID.

String
build_number

Cluster build number composed of the cluster's major, minor and patch version numbers (for example, "2.2.0").

String
download_urls

Provides download links for versions of APC compatible this cluster.

Object
major

Apcera cluster major version number.

Integer
minor

Apcera cluster minor version number.

Integer
patch

Cluster patch number.

Integer
version

Cluster version string composed of the cluster's major, minor and patch version numbers (for example, "2.2.0").

String

VirtualNetwork

Describes a virtual network.

Name Description Type Notes
created_at

UNIX timestamp when the network was created.

Number
Read-only
created_by

Principal name of user who created the network.

String
Read-only
description

Network description.

String
fqn

Network's fully-qualified name.

String
Required
name

Network's local name.

String
Required
network_end_points

A list of network endpoints in the network.

VirtualNetworkEndpoint [ ]
subnet_info

Contains details about the network's subnets.

SubnetInfo
updated_at

UNIX timestamp when the network was last updated.

Number
Read-only
updated_by

Principal name of user who last updated the network.

String
Read-only
uuid

Network's unique ID.

String
Read-only
version_id

Auto-incrementing version number for the network. This value should be the most recent value returned by GET /networks.

Integer

VirtualNetworkEndpoint

Name Description Type Notes
end_point_interface

A list of interfaces associated with the job.

VirtualNetworkEndpointInterface [ ]
fqn

Fully-qualified name of the job the endpoint is attached to.

String
network_fqn

Fully-qualified name of the network that the endpoint belongs to.

String
uuid

The UUID of the network endpoint.

String

VirtualNetworkEndpointInterface

Name Description Type Notes
hardware_addr

Unique identifier assigned to the network interface.

String
ipv4_addr

Virtual IP address assigned to the instance.

String
uuid

The UUID of the network endpoint.

String