Apcera REST API Reference

This reference lists and describes API endpoints of the Apcera REST API. You can also download the OpenAPI (Swagger) specification that describes the Apcera API endpoints and model objects.

Endpoint Description
GET /v1/apc/download/{platform} Downloads APC for the specified platform.
GET /v1/apc/version Returns the version of APC available for download from the cluster.
GET /v1/audit Returns audit log items.
POST /v1/bindings Creates a binding (link) between two jobs or between a job and a service.
GET /v1/cluster/admin Returns the name and email for the cluster administrator.
GET /v1/info Returns information about the API server.
GET /v1/instance_managers Returns a list of the cluster's instance managers.
GET /v1/instance_managers/{uuid} Returns the specified instance manager.
GET /v1/instance_managers/{uuid}/instances Returns a list of instances managed by the specified instance manager.
POST /v1/instances/{uuid}/snapshot Creates a snapshot of a capsule.
GET /v1/jobs Returns a list of jobs on the cluster.
POST /v1/jobs Creates a new job.
POST /v1/jobs/docker Creates a new job from a Docker image.
GET /v1/jobs/health Retrieves health information for one or more jobs.
GET /v1/jobs/routes Returns a map of all job routes to the UUIDs of the jobs that are assigned each route.
GET /v1/jobs/routes/{endpoint} Returns a map a route endpoint to UUIDs of jobs that share that endpoint.
DELETE /v1/jobs/{uuid} Deletes the specified job.
GET /v1/jobs/{uuid} Returns the specified job.
PUT /v1/jobs/{uuid} Updates the specified job.
GET /v1/jobs/{uuid}/files Returns a directory listing for the specified job.
GET /v1/jobs/{uuid}/instances Returns a list of instances for the specified job.
DELETE /v1/jobs/{uuid}/instances/{instance_uuid} Issues a stop request to a specific instance of a job.
GET /v1/jobs/{uuid}/logs Returns logs for the specified job.
GET /v1/jobs/{uuid}/logs/drains Returns log drains for the specified job.
POST /v1/jobs/{uuid}/logs/drains Creates a log drain for the specified job.
DELETE /v1/jobs/{uuid}/logs/drains/{drain_uuid} Deletes a log drain from a job.
POST /v1/jobs/{uuid}/networks Joins a job to a network.
DELETE /v1/jobs/{uuid}/networks/{network_uuid} Remove a job from a network.
POST /v1/manifests Deploy apps, services, and networks via a multi-resource manifest.
POST /v1/manifests/expansion Expands substitution variables in a multi-resource manifest and returns the expanded manifest.
GET /v1/namespace/default Returns the default namespace.
GET /v1/networks Returns a list of virtual networks.
POST /v1/networks Creates a new virtual network.
GET /v1/networks/{uuid} Returns the specified virtual network.
DELETE /v1/networks/{uuid} Deletes a virtual network.
GET /v1/packages Returns a list of packages.
POST /v1/packages Creates a new package.
POST /v1/packages/dependencies Returns a list of packages that fulfill the specified dependency type and name.
GET /v1/packages/resources/{uuid} Downloads the specified package's binary resource.
PUT /v1/packages/{packageid}/resources/{resourceid} Uploads a package's binary resource.
DELETE /v1/packages/{uuid} Deletes the specified package.
GET /v1/packages/{uuid} Returns the specified package.
PUT /v1/packages/{uuid} Updates the specified package's properties.
GET /v1/policy Returns a list of policy documents sorted by name.
GET /v1/policy/{name} Returns the contents of the named policy document.
PUT /v1/policy Adds or updates one or more policy documents.
DELETE /v1/policy Deletes one or more policy documents.
GET /v1/providers Returns a list of providers.
POST /v1/providers Creates a new provider.
DELETE /v1/providers/{uuid} Deletes a provider.
GET /v1/rules Lists semantic pipeline rules.
POST /v1/rules Creates a new semantic pipeline rule.
DELETE /v1/rules/{uuid} Deletes a semantic pipeline rule.
GET /v1/rules/{uuid} Returns a semantic pipeline rule.
GET /v1/runtimes Returns a list of supported runtimes.
GET /v1/services Returns a list of services.
POST /v1/services Creates a new service.
DELETE /v1/services/{uuid} Deletes a service.
GET /v1/sim Runs a policy simulation against existing policy in the system.
PUT /v1/sim Runs a policy simulation with the ability to add additional policy documents to the simulation request.
GET /v1/stagingpipelines Returns a list of staging pipelines.
POST /v1/stagingpipelines Creates a staging pipeline.
DELETE /v1/stagingpipelines/{uuid} Deletes a staging pipeline.
GET /v1/stagingpipelines/{uuid} Returns a staging pipeline.
PUT /v1/stagingpipelines/{uuid} Updates a staging pipeline.
GET /v1/tags Returns a list of tags defined on instance managers.
GET /v1/tasks/{uuid} Returns the specified Task object.
POST /v1/unbind Removes a binding between a job and a service.
POST /v1/unlink Removes a link between two jobs.
GET /v1/version Returns the cluster version number.

GET /v1/apc/download/{platform}

Downloads APC for a given platform. A successful response is an HTTP 301 status code. The Location HTTP header contains the URL where you can download the APC binary. The response body is an HTML <a/> tag whose href attribute is the same download URL.

Request Parameters

Name Description Type
platform The platform for which to download APC. Valid values are: linux_amd64, linux, osx_amd64, darwin_amd64, darwin, osx. String

Example

Request
GET /v1/apc/download/linux HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

Response

HTTP/1.1 301 Moved Permanently
Content-Length: 108
Content-Type: text/html; charset=utf-8
Location: https://s3-us-west-2.amazonaws.com/apc-updates/apc_latest_linux_amd64.zip

<a href="https://s3-us-west-2.amazonaws.com/apc-updates/apc_latest_linux_amd64.zip">Moved Permanently</a>.

GET /v1/apc/version

Returns the version of APC available for download from the cluster.

Request

GET /v1/apc/version HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer eyJ0eXAiOiIiLCJhbGciOiIifQ....
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "version": "0.20.0"
}

GET /v1/audit

Queries the audit log for items that match the specified query parameters and returns a list of AuditLogItem objects. The maximum number of results returned in a single response is determined by the limit parameter (default is 200). The offset query parameter lets you specify the first record returned in a result set.

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 automatically included in the response that provide the API endpoints to retrieve the previous and next set of query results, respectively. See example below.

Request Parameters

Name Description Type
end_time UNIX timestamp. If specified, only events that occurred on or before the specified time are returned in the response. Number
event_type One of the valid audit log item event types. If specified, only log items of the specified type are returned in the response. By default, audit log items for all event types are returned. String
fqn If specified, only events on the resource specified by fqn are returned in the response. The value must be URL-encoded. String
limit Limits the number of records included in the response (default is 200). Maximum limit is 1000. Integer
offset Offset of first record to return in response (default is 0). Integer
reverse If present, reverses the default ordering of query results from most recent first to least recent first. Integer
start_time UNIX timestamp. If specified, only events that occurred on or after the specified time are returned in the response. Number

Notes:

  • The fqn parameter can also specify an FQN segment, which may include wild cards for the resource type. For example:

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

Example

The following example requests audit log items of type network.join, and limits the number of items in the response to two items. As the query matches more than two results, the HTTP response includes Next and Prev headers that provide the API endpoints to obtain the next and previous sets of query results, respectively. The offset and limit parameters are set to the necessary values to obtain the proper result sets. For the Next API endpoint URI, the offset is set to the current offset plus the value of the limit parameter; for the Prev API endpoint the offset is set to the current offset minus the value of the limit parameter.

Request
GET /v1/audit?event_type=network.join&limit=2 HTTP/1.1
Host: api.example.apcera-platform.io
Authorization: Bearer <token>
Content-Type: application/json
Response

The response is an array of AuditLogItem objects that matched the specified query parameters. In this case, the query matches more results than specified limit, so the response includes HTTP headers (Next and Prev) that provide URIs to get the next and previous sets of audit log items in the same query. These URIs contain the original query parameters plus an offset parameter that is automatically updated to provide the correct next/previous query results.

HTTP/1.1 200 OK
Next: http://api.example.apcera-platform.io/v1/audit?event_type=network.join&limit=2&offset=2
Prev: http://api.example.apcera-platform.io/v1/audit?event_type=network.join&limit=2&offset=0

[
  {
    "uuid": "bab8c41d-9bc4-11e6-a253-06bc450cb24a",
    "event_type_int": 6002,
    "event_type": "network.join",
    "fqn": "job::/myapps::mycentos-4",
    "localname": "mycentos-4",
    "namespace": "/myapps",
    "on_behalf_of": "admin@apcera.me",
    "audit_payload": {
      "patches": [
        {
          "op": "add",
          "path": "network_ref/uuid",
          "value": "e9a76724-d5c3-4a51-9fb0-8b5e70a82018"
        }
      ]
    },
    "principal_name": "api_server@apcera.me",
    "resource_type": "job",
    "timestamp": 1477517992
  },
  {
    "uuid": "b2839a08-9bc4-11e6-a24e-06bc450cb24a",
    "event_type_int": 6002,
    "event_type": "network.join",
    "fqn": "job::/myapps::mycentos-3",
    "localname": "mycentos-3",
    "namespace": "/myapps",
    "on_behalf_of": "admin@apcera.me",
    "audit_payload": {
      "patches": [
        {
          "op": "add",
          "path": "network_ref/uuid",
          "value": "85ca75fd-0165-4c49-842c-9c3b0464b706"
        }
      ]
    },
    "principal_name": "api_server@apcera.me",
    "resource_type": "job",
    "timestamp": 1477517979
  }
]

GET /v1/audit/events

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

Request Parameters

None.

Example

Request
GET /v1/audit/events HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

[
    "job.addroute",
    "job.packagedeny",
    "job.updatememory",
    "policy.delete",
    "job.addbinding",
    "policy.update",
    "service.create",
    "service.update",
    "gateway.promote",
    "quota.update",
    "sempiperule.create",
    "stagpipe.create",
    "job.addlink",
    "job.packagesetdefault",
    "pkg.update",
    "job.removebinding",
    "pkg.get",
    "service.unbind",
    "pkg.delete",
    "job.demote",
    "job.packageallow",
    "job.updatedisk",
    "pkg.create",
    "auth.issue",
    "job.removelink",
    "job.delete",
    "job.packagelock",
    "job.packageunlock",
    "policy.add",
    "service.bind",
    "provider.create",
    "provider.delete",
    "job.update",
    "job.promote",
    "job.packageretire",
    "route.map",
    "service.delete",
    "cluster.update",
    "job.removeroute",
    "job.start",
    "job.stop",
    "sempiperule.delete",
    "stagpipe.update",
    "stagpipe.delete",
    "job.create"
]

POST /v1/bindings

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

Request Parameters

Name Description Type
POST body Binding object. String

To create a service binding, the POST body payload must include job_fqn and service_fqn (or provider_fqn) fields. To create a job link, the object must include job_fqn and target_job_fqn fields. See examples below.

Examples

Service binding example: The following creates a binding between a job and an http service.

Request
POST /v1/bindings HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

{
    "job_fqn":"job::/dev::myapp",
    "name":"my_binding",
    "service_fqn":"service::/apcera::http"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "env_var": [
        "HTTP_URI",
        "MY_BINDING_URI"
    ],
    "fqn": "binding::/::23AA2C9E-EAB6-4930-963F-855C48DCEF6A",
    "job_fqn": "job::/dev::myapp",
    "name": "my_binding",
    "service_fqn": "service::/apcera::http",
    "uuid": "1241dd75-e477-4db6-886e-8e294eb40bc7"
}

Job Link example: The following creates a job link between two jobs.

Request

POST /v1/bindings HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

{
    "job_fqn":"job::/dev::myapp",
    "target_job_fqn":"job::/dev::myapp-2",
    "target_job_port": 0,
    "name": "my_link"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "fqn": "binding::/::BC95C6E8-C97E-4369-A058-8FB196094FA3",
    "name": "my_link",
    "target_job_fqn": "job::/dev::myapp-2"
}

GET /v1/cluster/admin

Returns the name and email of the cluster administrator.

Request Parameters

None.

Example

Request
GET /v1/cluster/admin HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

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

GET /v1/info

Returns information about the API server.

Request Parameters

None.

Example

Request
GET /v1/info HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "cluster_domain": "apcera.me",
    "name": "continuum",
    "url": "http://api.try.apcera.net/"
}

GET /v1/instance_managers

Returns an array of instance managers.

Request Parameters

None.

Example

Request
GET /v1/instance_managers HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response

The response is an array of instance managers.

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "ResourcesProvisioned": {
            "cpu": 0,
            "disk": 1610612736,
            "memory": 67108864,
            "netmax": 0,
            "network": 60000000
        },
        "ResourcesTotal": {
            "cpu": 1000000,
            "disk": 47047507968,
            "memory": 4145549312,
            "netmax": 0,
            "network": 1099511627776
        },
        "hostname": "vagrant-046bfd16",
        "num_instances": 6,
        "start_time": "2015-10-15T00:07:09.158167313Z",
        "system_tags": [
            "job-d731681c-b3cf-46e0-8246-23dd5d24ed18",
            "job-48ac0e4d-317a-4f1d-8a21-70fdb79d8488",
            "job-f1df62a1-d428-4e9e-9fa3-488b69fbf322",
            "job-b95d4476-af80-48fb-945f-eac49a3eec6e",
            "job-d939f89c-78c9-4f0b-9ca5-6b7bade12650",
            "job-b8c694dc-dd11-408b-92ec-af8530afd9b3",
            "job-ff1060f7-192c-477a-99b8-9f948582913c"
        ],
        "tags": [
            "unknown",
            "host-046bfd16"
        ],
        "uuid": "73c1d458-415f-4e5c-bfc5-2ea637914bbf"
    },
    {
        "ResourcesProvisioned": {
            "cpu": 0,
            "disk": 1879048192,
            "memory": 75497472,
            "netmax": 0,
            "network": 70000000
        },
        "ResourcesTotal": {
            "cpu": 1000000,
            "disk": 47047507968,
            "memory": 4145549312,
            "netmax": 0,
            "network": 1099511627776
        },
        "hostname": "vagrant-786f1f0f",
        "num_instances": 7,
        "start_time": "2015-10-15T00:06:49.953127187Z",
        "system_tags": [
            "job-9d144e04-82d9-420d-90ed-1e7a00e5b8c5",
            "job-95e4156f-938a-45fe-8403-53a9f110e681",
            "job-b8c694dc-dd11-408b-92ec-af8530afd9b3",
            "job-9de4c964-b222-4871-92e0-31eb4be1b71d",
            "job-a2379c7a-ea55-4bcf-8dba-9aa712fe159c",
            "job-b8c769fe-f0d5-4a20-9d0d-ddc356448585",
            "job-b95d4476-af80-48fb-945f-eac49a3eec6e",
            "job-ff1060f7-192c-477a-99b8-9f948582913c"
        ],
        "tags": [
            "unknown",
            "host-786f1f0f"
        ],
        "uuid": "887eb315-d7de-4b66-ab32-dbd7219863bd"
    }
]

GET /v1/instance_managers/{uuid}

Returns the instance manager with the specified UUID.

Request Parameters

Name Description Type
uuid The unique identifier of the instance manager. String

Examples

Request
GET /v1/instance_managers/887eb315-d7de-4b66-ab32-dbd7219863bd HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "ResourcesProvisioned": {
        "cpu": 0,
        "disk": 1879048192,
        "memory": 75497472,
        "netmax": 0,
        "network": 70000000
    },
    "ResourcesTotal": {
        "cpu": 1000000,
        "disk": 47047507968,
        "memory": 4145549312,
        "netmax": 0,
        "network": 1099511627776
    },
    "hostname": "vagrant-786f1f0f",
    "num_instances": 7,
    "start_time": "2015-10-15T00:06:49.953127187Z",
    "system_tags": [
        "job-9de4c964-b222-4871-92e0-31eb4be1b71d",
        "job-a2379c7a-ea55-4bcf-8dba-9aa712fe159c",
        "job-b8c769fe-f0d5-4a20-9d0d-ddc356448585",
        "job-b95d4476-af80-48fb-945f-eac49a3eec6e",
        "job-ff1060f7-192c-477a-99b8-9f948582913c",
        "job-9d144e04-82d9-420d-90ed-1e7a00e5b8c5",
        "job-95e4156f-938a-45fe-8403-53a9f110e681",
        "job-b8c694dc-dd11-408b-92ec-af8530afd9b3"
    ],
    "tags": [
        "host-786f1f0f",
        "unknown"
    ],
    "uuid": "887eb315-d7de-4b66-ab32-dbd7219863bd"
}

GET /v1/instance_managers/{uuid}/instances

Returns a list of instances managed by the specified instance manager.

Request Parameters

Name Description Type
uuid The unique identifier of the instance manager. String

Example

Request
GET /v1/instance_managers/887eb315-d7de-4b66-ab32-dbd7219863bd/instances HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "job_fqn": "job::/apcera/service-gateways::ipm",
        "job_uuid": "9d144e04-82d9-420d-90ed-1e7a00e5b8c5",
        "resources": {
            "cpu": 0,
            "disk": 268435456,
            "memory": 8388608,
            "netmax": 0,
            "network": 10000000
        },
        "start_time": "2015-10-15T00:07:21.153793098Z",
        "uuid": "b34e5cbb-7f2a-4607-9bf6-307893353ed1"
    },
    {
        "job_fqn": "job::/apcera/service-gateways::postgres",
        "job_uuid": "b8c769fe-f0d5-4a20-9d0d-ddc356448585",
        "resources": {
            "cpu": 0,
            "disk": 268435456,
            "memory": 8388608,
            "netmax": 0,
            "network": 10000000
        },
        "start_time": "2015-10-15T00:07:21.478997472Z",
        "uuid": "b2a70c95-c09e-4c8e-85f1-56f92e949c61"
    },
    {
        "job_fqn": "job::/apcera::lucid",
        "job_uuid": "ff1060f7-192c-477a-99b8-9f948582913c",
        "resources": {
            "cpu": 0,
            "disk": 268435456,
            "memory": 25165824,
            "netmax": 0,
            "network": 10000000
        },
        "start_time": "2015-10-15T00:07:43.970669122Z",
        "uuid": "63f52119-830e-499e-9611-fabece1df175"
    }
]

GET /v1/jobs

Returns an array of job objects, optionally filtered by one or more query parameters. You can also paginate results and control the number of jobs returned per-page.

Request Parameters

Name Description Required Schema Default
BindingFQN Filter jobs with a specific binding FQN. false string (string)  
count Limits the number of jobs returned in the response. By default, all jobs are returned. false string (string)  
docker_origin If the job was created from a Docker image, provides information about the source Docker image name and registry. false DockerOrigin  
FQN FQN of job to return. false string (string)  
health If true, the response includes health metrics for the job. false string (boolean)  
ids Comma-separated list of UUIDs of jobs to return. false string (string)  
matchPartialFQN If true, jobs that partially match the specified FQN are returned. false string (boolean)  
name Local name of job(s) to return. false string (string)  
page Specifies the number of the results page to fetch. By default, the first page of results is returned. false string (string)  
package_id Return jobs that use the package specified by UUID. false string (string)  
ProviderFQN Return jobs bound to services on the specified provider. false string (string)  
ServiceFQN Return jobs bound to the specified service. false string (string)  
tag Returns jobs with the specified tags. false array (string)  
label Return jobs with the given label or labels. If a label value is provided, then the label must also have that value. The query string can contain multiple label parameters, and only jobs that meet ALL the label requirements are returned. See examples below. false string  

Examples

Example 1: The following example returns a list of all jobs (response abbreviated for readability).

Request
GET /v1/jobs HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "uuid": "8788e721-b9cb-4ece-829a-5186bae92180",
    "updated_by": "stagehand@apcera.me",
    "created_by": "stagehand@apcera.me",
    "updated_at": "2015-10-08T17:38:12.599341182Z",
    "created_at": "2015-10-08T17:38:08.130323466Z",
    "bindings": {
      "binding::/apcera/semantic-pipelines::outside-dns-http": {
        "uuid": "40e0b765-ba08-4a56-9365-feb588a20d76",
        "name": "outside-dns-http",
        "fqn": "binding::/apcera/semantic-pipelines::outside-dns-http",
        "job_fqn": "job::/apcera/semantic-pipelines::http",
        "env_var": [
          "NETWORK_URI",
          "OUTSIDEDNSHTTP_URI"
        ],
        "parameters": {
          "ipnet": "any",
          "portrange": "53",
          "protocol": "udp"
        },
        "service_fqn": "service::/apcera::outside-dns"
      },
      "binding::/apcera/semantic-pipelines::outside-http-http": {
        "uuid": "d6079293-de28-4520-872e-1ddc17e29083",
        "name": "outside-http-http",
        "fqn": "binding::/apcera/semantic-pipelines::outside-http-http",
        "job_fqn": "job::/apcera/semantic-pipelines::http",
        "env_var": [
          "NETWORK_URI",
          "OUTSIDEHTTPHTTP_URI"
        ],
        "parameters": {
          "ipnet": "any",
          "portrange": "80",
          "protocol": "tcp"
        },
        "service_fqn": "service::/apcera::outside-http"
      }
    },
    "ports": [
      {
        "number": 0,
        "optional": false
      }
    ],
    "logs": [
      {
        "file": "/logs/stdout.*.log",
        "channel": "job.$JOB_UUID.stdout"
      },
      {
        "file": "/logs/stderr.*.log",
        "channel": "job.$JOB_UUID.stderr"
      }
    ],
    "name": "http",
    "fqn": "job::/apcera/semantic-pipelines::http",
    "num_instances": 1,
    "packages": [
      {
        "uuid": "20468f8b-7824-48f1-8349-976a79e5abbc",
        "state": "unknown",
        "source": "user"
      },
      {
        "uuid": "20468f8b-7824-48f1-8349-976a79e5abbc",
        "state": "ready",
        "source": "system"
      }
    ],
    "processes": {
      "pipeline": {
        "start_command_raw": [],
        "start_command": "./sp_http -sp-config-json-file=http-base.cfg -sp-config-environ-ok -sp-config-httppost-source='0.0.0.0/0 ::/0' -admin-http-address='0.0.0.0:5602'",
        "start_command_timeout": 0,
        "stop_command_raw": [],
        "stop_command": "",
        "stop_timeout": 0
      }
    },
    "resources": {
      "cpu": 0,
      "memory": 50331648,
      "disk": 268435456,
      "network": 10000000,
      "netmax": 0
    },
    "rollout": {
      "force_stop_old_instances_after": 120,
      "flapping_minimum_restarts": 3,
      "flapping_percent": 0.5,
      "flapping_window": 300,
      "errored_state_window": 0
    },
    "restart": {
      "restart_mode": "always",
      "maximum_attempts": 0
    },
    "hard_scheduling_tags": {},
    "soft_scheduling_tags": {},
    "state": "ready",
    "tags": {
      "pipeline": "http"
    },
    "weight": 0,
    "version_id": 3
  },
  {
    "uuid": "d1d7ecde-b408-4610-9b4e-d2996ac0b935",
    "updated_by": "",
    "created_by": "stagehand@apcera.me",
    "updated_at": "2015-10-08T17:38:08.147651389Z",
    "created_at": "2015-10-08T17:38:08.147651389Z",
    "ports": [
      {
        "number": 0,
        "optional": false
      }
    ],
    "logs": [
      {
        "file": "/logs/stdout.*.log",
        "channel": "job.$JOB_UUID.stdout"
      },
      {
        "file": "/logs/stderr.*.log",
        "channel": "job.$JOB_UUID.stderr"
      }
    ],
    "name": "memcache",
    "fqn": "job::/apcera/semantic-pipelines::memcache",
    "num_instances": 1,
    "packages": [
      {
        "uuid": "20468f8b-7824-48f1-8349-976a79e5abbc",
        "state": "unknown",
        "source": "user"
      },
      {
        "uuid": "20468f8b-7824-48f1-8349-976a79e5abbc",
        "state": "ready",
        "source": "system"
      }
    ],
    "processes": {
      "pipeline": {
        "start_command_raw": [],
        "start_command": "./sp_memcache -sp-config-json-file=memcache-base.cfg -sp-config-environ-ok -sp-config-httppost-source='0.0.0.0/0 ::/0' -admin-http-address='0.0.0.0:5602'",
        "start_command_timeout": 0,
        "stop_command_raw": [],
        "stop_command": "",
        "stop_timeout": 0
      }
    },
    "resources": {
      "cpu": 0,
      "memory": 50331648,
      "disk": 268435456,
      "network": 10000000,
      "netmax": 0
    },
    "rollout": {
      "force_stop_old_instances_after": 120,
      "flapping_minimum_restarts": 3,
      "flapping_percent": 0.5,
      "flapping_window": 300,
      "errored_state_window": 0
    },
    "restart": {
      "restart_mode": "always",
      "maximum_attempts": 0
    },
    "hard_scheduling_tags": {},
    "soft_scheduling_tags": {},
    "state": "ready",
    "tags": {
      "pipeline": "memcache"
    },
    "weight": 0,
    "version_id": 1
  }
]

Example 2: The following example returns all jobs that have the tag app.

Request
GET /v1/jobs?tag=app HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "created_at": "2015-10-15T00:07:43.273420705Z",
        "created_by": "stagehand@apcera.me",
        "fqn": "job::/apcera::continuum-guide",
        "hard_scheduling_tags": {},
        "logs": [
            {
                "channel": "job.$JOB_UUID.stdout",
                "file": "/logs/stdout.*.log"
            },
            {
                "channel": "job.$JOB_UUID.stderr",
                "file": "/logs/stderr.*.log"
            }
        ],
        "name": "continuum-guide",
        "num_instances": 2,
        "packages": [
            {
                "source": "user",
                "state": "unknown",
                "uuid": "379e2d21-81f6-4af1-953c-9cb118e186d6"
            },
            {
                "source": "system",
                "state": "ready",
                "uuid": "379e2d21-81f6-4af1-953c-9cb118e186d6"
            }
        ],
        "ports": [
            {
                "number": 0,
                "optional": false,
                "routes": [
                    {
                        "endpoint": "continuum-guide.vagrant.apcera.net",
                        "type": "http",
                        "weight": 0
                    },
                    {
                        "endpoint": "docs.vagrant.apcera.net",
                        "type": "http",
                        "weight": 0
                    }
                ]
            }
        ],
        "processes": {
            "app": {
                "start_command": "",
                "start_command_raw": [],
                "start_command_timeout": 0,
                "stop_command": "",
                "stop_command_raw": [],
                "stop_timeout": 0
            }
        },
        "resources": {
            "cpu": 0,
            "disk": 268435456,
            "memory": 8388608,
            "netmax": 0,
            "network": 10000000
        },
        "restart": {
            "maximum_attempts": 0,
            "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
        },
        "soft_scheduling_tags": {},
        "state": "started",
        "tags": {
            "app": "continuum-guide",
            "autostart": "yes"
        },
        "updated_at": "2015-10-15T00:07:43.273420705Z",
        "updated_by": "",
        "uuid": "b95d4476-af80-48fb-945f-eac49a3eec6e",
        "version_id": 1,
        "weight": 0
    },
    {
        "created_at": "2015-10-15T00:07:43.919206367Z",
        "created_by": "stagehand@apcera.me",
        "fqn": "job::/apcera::lucid",
        "hard_scheduling_tags": {},
        "logs": [
            {
                "channel": "job.$JOB_UUID.stdout",
                "file": "/logs/stdout.*.log"
            },
            {
                "channel": "job.$JOB_UUID.stderr",
                "file": "/logs/stderr.*.log"
            }
        ],
        "name": "lucid",
        "num_instances": 2,
        "packages": [
            {
                "source": "user",
                "state": "unknown",
                "uuid": "9a2ef589-cd27-45d0-84b1-06b5fc6e4ab3"
            },
            {
                "source": "system",
                "state": "ready",
                "uuid": "9a2ef589-cd27-45d0-84b1-06b5fc6e4ab3"
            }
        ],
        "ports": [
            {
                "number": 0,
                "optional": false,
                "routes": [
                    {
                        "endpoint": "console.vagrant.apcera.net",
                        "type": "http",
                        "weight": 0
                    }
                ]
            }
        ],
        "processes": {
            "app": {
                "start_command": "",
                "start_command_raw": [],
                "start_command_timeout": 0,
                "stop_command": "",
                "stop_command_raw": [],
                "stop_timeout": 0
            }
        },
        "resources": {
            "cpu": 0,
            "disk": 268435456,
            "memory": 25165824,
            "netmax": 0,
            "network": 10000000
        },
        "restart": {
            "maximum_attempts": 0,
            "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
        },
        "soft_scheduling_tags": {},
        "state": "started",
        "tags": {
            "app": "lucid",
            "autostart": "yes"
        },
        "updated_at": "2015-10-15T00:07:43.919206367Z",
        "updated_by": "",
        "uuid": "ff1060f7-192c-477a-99b8-9f948582913c",
        "version_id": 1,
        "weight": 0
    }
]

Example 3: The following example returns all jobs with the label named costcenter, regardless of its value. Response abbreviated for readability.

Request
GET /v1/jobs?label=costcenter HTTP/1.1
Host: api.starlet.continuum-demo.io
Authorization: Bearer ...
Content-Type: application/json
Response
[
    {
        "uuid": "1cbbbd35-1790-4f1c-92e1-2ba1ab359c0a",
        "updated_by": "admin@apcera.me",
        "created_by": "admin@apcera.me",
        ...,
        "labels": {
            "costcenter": "67890",
            "team": "eng"
        },
        "weight": 0,
        "version_id": 2,
        "network_ref": null
    },
    {
        "uuid": "13171858-e20a-4628-88f4-d94056b5f83b",
        "updated_by": "",
        "created_by": "admin@apcera.me",
        ...,
        "labels": {
            "costcenter": "12345",
            "team": "documentation"
        },
        "weight": 0,
        "version_id": 1,
        "network_ref": null
    }
]

Example 4: The following example returns all jobs that have a label named team (regardless of value) and a costcenter label with the value of "12345". Response abbreviated for readability.

Request
GET /v1/jobs?label=costcenter=12345&label=team HTTP/1.1
Host: api.starlet.continuum-demo.io
Authorization: Bearer ...
Content-Type: application/json
Response
[
    {
        "uuid": "13171858-e20a-4628-88f4-d94056b5f83b",
        "updated_by": "",
        "created_by": "admin@apcera.me",
        ...,
        "labels": {
            "costcenter": "12345",
            "team": "documentation"
        },
        "weight": 0,
        "version_id": 1,
        "network_ref": null
    }
]

POST /v1/jobs

Creates and returns a new job.

Request Parameters

Name Description Type
POST body Job object to create. String

Example

Request
POST /v1/jobs HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

{
  "fqn": "job::/test::staticsite2",
  "labels": {
      "team": "documentation",
      "costcenter": "12345"
  },
  "name": "staticsite2",
  "ports": [
    {
      "number": 0,
      "optional": false,
      "routes": [
        {
          "endpoint": "staticsite2.vagrant.apcera.net",
          "type": "http",
          "weight": 0
        }
      ]
    }
  ],
  "packages": [
    {
      "uuid": "f93d73e2-9047-46b2-82b5-255f12013d2f"
    }
  ],
  "processes": {
    "app": {
      "start_command": "",
      "start_command_raw": null,
      "start_command_timeout": 30,
      "stop_command": "",
      "stop_command_raw": null,
      "stop_timeout": 5
    }
  },
  "resources":{
    "cpu":0,
    "disk":1073741824,
    "memory":268435456,
    "netmax":0,
    "network":5000000
  },
  "restart":{
    "maximum_attempts":0,
    "restart_mode":"always"
  },
  "rollout":{
    "errored_state_window":0,
    "flapping_minimum_restarts":0,
    "flapping_percent":0,
    "flapping_window":0,
    "force_stop_old_instances_after":0
  },
  "tags": {
    "app": "staticsite2"
  }
}
Response
HTTP/1.1 200 OK
Content-Type: application/json
Location: http://api.try.apcera.net/v1/jobs/7d98c2c1-1ded-4e3c-864f-61904e97d0f0

{
    "created_at": "2015-10-15T15:59:31.417007961Z",
    "created_by": "joe.user@apcera.com",
    "fqn": "job::/test::staticsite",
    "hard_scheduling_tags": {},
    "logs": [
        {
            "channel": "job.$JOB_UUID.stdout",
            "file": "/logs/stdout.*.log"
        },
        {
            "channel": "job.$JOB_UUID.stderr",
            "file": "/logs/stderr.*.log"
        }
    ],
    "labels": {
       "team": "documentation",
       "costcenter": "12345"
    },
    "name": "staticsite",
    "num_instances": 1,
    "packages": [
        {
            "source": "user",
            "state": "unknown",
            "uuid": "f93d73e2-9047-46b2-82b5-255f12013d2f"
        },
        {
            "source": "system",
            "state": "ready",
            "uuid": "11d3244f-b9e9-4ee0-9ebe-079c082acfd4"
        },
        {
            "source": "system",
            "state": "ready",
            "uuid": "d77faf56-e38b-41e3-8280-be9c99b65992"
        },
        {
            "source": "system",
            "state": "ready",
            "uuid": "f93d73e2-9047-46b2-82b5-255f12013d2f"
        }
    ],
    "ports": [
        {
            "number": 0,
            "optional": false,
            "routes": [
                {
                    "endpoint": "staticsite.vagrant.apcera.net",
                    "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": {
        "maximum_attempts": 0,
        "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
    },
    "soft_scheduling_tags": {},
    "state": "ready",
    "tags": {
        "app": "staticsite"
    },
    "updated_at": "2015-10-15T15:59:31.417007961Z",
    "updated_by": "",
    "uuid": "7d98c2c1-1ded-4e3c-864f-61904e97d0f0",
    "version_id": 1,
    "weight": 0
}

POST /v1/jobs/docker

Downloads a Docker image from a registry and creates a job to run it. The response is the URI of the corresponding Task object you can use to monitor the progress of the creation of the application from the Docker image. There are two ways to use this URI to track progress of the operation:

Also see Create an App from a Docker image in Apcera REST API Recipes.

Request Parameters

Name Description Type
POST body Object that specifies Docker image URL and properties of newly created job. CreateDockerJobRequest

Example

This example creates and starts a job from the latest version of the deis/helloworld image on Docker Hub. Change the namespace in the job_fqn field and the domain in the routes field to match your Apcera cluster's environment.

Request
POST /v1/jobs/docker HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer eyJ0eXAiOiI...
Content-Type: application/json

{
  "allow_egress":true,
  "exposed_ports":[
    80
  ],
  "image_url":"https://registry-1.docker.io/deis/helloworld:latest",
  "job_fqn":"job::/sandbox/user::hellodocker",
  "resources":{
    "cpu":0,
    "disk":1073741824,
    "memory":268435456,
    "netmax":0,
    "network":5000000
  },
  "restart_config":{
    "maximum_attempts":0,
    "restart_mode":"no"
  },
  "routes":{
    "http://hellodocker.sandbox.user.try.apcera.net":80
  },
  "start":true
}
Response

The response payload contains a location field whose value is the URI (GET /v1/tasks/{uuid}) of the corresponding Task object that is tracking the progress of the API call.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "location":"http://api.try.apcera.net/v1/tasks/b68d89a0-5b78-462b-8ec6-84edeb5ac02a"
}

There are two ways to use this URI to track progress of the operation:

GET /v1/jobs/health

Retrieves health status for one or more jobs.

Request Parameters

Name Description Type
ids Comma-separated list of job UUIDs. String

Example

Request
GET /v1/jobs/health?ids=371503a4-0c71-4c56-9f71-64eef7833112,654a0c9d-215a-4947-99cc-21d642fb05ff HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "uuid": "371503a4-0c71-4c56-9f71-64eef7833112",
    "flapping": false,
    "score": 1,
    "instance_state_count": {
      "RUNNING": 1,
      "STOPPED": 1
    }
  },
  {
    "uuid": "654a0c9d-215a-4947-99cc-21d642fb05ff",
    "flapping": false,
    "score": 0,
    "instance_state_count": {
      "TEARDOWN": 1
    }
  }
]

GET /v1/jobs/routes

Returns a map of all job routes in the cluster to UUIDs of the jobs that are assigned each route.

Request Parameters

None.

Example

Request
GET /v1/jobs/routes HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "docs.vagrant.apcera.net": [
        "b95d4476-af80-48fb-945f-eac49a3eec6e"
    ],
    "myapp-2.dev.vagrant.apcera.net": [
        "654a0c9d-215a-4947-99cc-21d642fb05ff",
        "157972bf-e082-4aaa-8ef6-e75e080ae467"
    ],
    "myapp.dev.vagrant.apcera.net": [
        "371503a4-0c71-4c56-9f71-64eef7833112"
    ]
}

GET /v1/jobs/routes/{endpoint}

Returns a map of the specified route endpoint to UUIDs of jobs that share that endpoint. The endpoint value must be Base64-encoded with URL-safe characters (see https://en.wikipedia.org/wiki/Base64#URL_applications).

Request Parameters

Name Description Type
endpoint URL-safe, Base64-encoded version of the route endpoint. String

Example

Request
GET /v1/jobs/routes/bXlhcHAuZGV2LnZhZ3JhbnQuYXBjZXJhLm5ldA== HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "myapp.dev.vagrant.apcera.net": [
        "371503a4-0c71-4c56-9f71-64eef7833112"
    ]
}

DELETE /v1/jobs/{uuid}

Deletes the specified job.

Request Parameters

Name Description Type
uuid UUID of the job to delete. String

Example

Request
DELETE /v1/jobs/654a0c9d-215a-4947-99cc-21d642fb05ff HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Response

A successful response indicates that the specified job was deleted.

HTTP/1.1 200 OK
Content-Type: application/json

GET /v1/jobs/{uuid}

Returns the specified job.

Request Parameters

Name Description Type
uuid UUID of the job to retrieve. String

Example

Request
GET /v1/jobs/b95d4476-af80-48fb-945f-eac49a3eec6e HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid": "b95d4476-af80-48fb-945f-eac49a3eec6e",
  "updated_by": "",
  "created_by": "stagehand@apcera.me",
  "updated_at": "2015-10-15T00:07:43.273420705Z",
  "created_at": "2015-10-15T00:07:43.273420705Z",
  "ports": [
    {
      "number": 0,
      "optional": false,
      "routes": [
        {
          "type": "http",
          "endpoint": "continuum-guide.vagrant.apcera.net",
          "weight": 0
        },
        {
          "type": "http",
          "endpoint": "docs.vagrant.apcera.net",
          "weight": 0
        }
      ]
    }
  ],
  "logs": [
    {
      "file": "/logs/stdout.*.log",
      "channel": "job.$JOB_UUID.stdout"
    },
    {
      "file": "/logs/stderr.*.log",
      "channel": "job.$JOB_UUID.stderr"
    }
  ],
  "name": "continuum-guide",
  "fqn": "job::/apcera::continuum-guide",
  "num_instances": 2,
  "packages": [
    {
      "uuid": "379e2d21-81f6-4af1-953c-9cb118e186d6",
      "state": "unknown",
      "source": "user"
    },
    {
      "uuid": "379e2d21-81f6-4af1-953c-9cb118e186d6",
      "state": "ready",
      "source": "system"
    }
  ],
  "processes": {
    "app": {
      "start_command_raw": [],
      "start_command": "",
      "start_command_timeout": 0,
      "stop_command_raw": [],
      "stop_command": "",
      "stop_timeout": 0
    }
  },
  "resources": {
    "cpu": 0,
    "memory": 8388608,
    "disk": 268435456,
    "network": 10000000,
    "netmax": 0
  },
  "rollout": {
    "force_stop_old_instances_after": 120,
    "flapping_minimum_restarts": 3,
    "flapping_percent": 0.5,
    "flapping_window": 300,
    "errored_state_window": 0
  },
  "restart": {
    "restart_mode": "always",
    "maximum_attempts": 0
  },
  "hard_scheduling_tags": {},
  "soft_scheduling_tags": {},
  "state": "started",
  "tags": {
    "app": "continuum-guide",
    "autostart": "yes"
  },
  "weight": 0,
  "version_id": 1
}

PUT /v1/jobs/{uuid}

Updates the specified job's properties with new values. You must include the entire job object in the update call, not just the fields that you want to change.

Request Parameters

Name Description Type
uuid UUID of the job to update. String
POST body Job object with updated properties. String

Example

The following example sets the job's state property to "started". To verify that an instance of the job is actually running after updating its state, poll the GET /v1/jobs/{uuid}/instances endpoint until the job instance's state is set to "RUNNING". For an example, see Starting an Application in Apcera REST API Recipes.

Request
PUT /v1/jobs/7d98c2c1-1ded-4e3c-864f-61904e97d0f0 HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

{
  "uuid": "7d98c2c1-1ded-4e3c-864f-61904e97d0f0",
  "updated_by": "",
  "created_by": "joe.user@apcera.com",
  "updated_at": "2015-10-15T15:59:31.417007961Z",
  "created_at": "2015-10-15T15:59:31.417007961Z",
  "ports": [
    {
      "number": 0,
      "optional": false,
      "routes": [
        {
          "type": "http",
          "endpoint": "staticsite.vagrant.apcera.net",
          "weight": 0
        }
      ]
    }
  ],
  "logs": [
    {
      "file": "/logs/stdout.*.log",
      "channel": "job.$JOB_UUID.stdout"
    },
    {
      "file": "/logs/stderr.*.log",
      "channel": "job.$JOB_UUID.stderr"
    }
  ],
  "name": "staticsite",
  "fqn": "job::/test::staticsite",
  "num_instances": 1,
  "packages": [
    {
      "uuid": "f93d73e2-9047-46b2-82b5-255f12013d2f",
      "state": "unknown",
      "source": "user"
    },
    {
      "uuid": "11d3244f-b9e9-4ee0-9ebe-079c082acfd4",
      "state": "ready",
      "source": "system"
    },
    {
      "uuid": "d77faf56-e38b-41e3-8280-be9c99b65992",
      "state": "ready",
      "source": "system"
    },
    {
      "uuid": "f93d73e2-9047-46b2-82b5-255f12013d2f",
      "state": "ready",
      "source": "system"
    }
  ],
  "processes": {
    "app": {
      "start_command_raw": [],
      "start_command": "",
      "start_command_timeout": 30,
      "stop_command_raw": [],
      "stop_command": "",
      "stop_timeout": 5
    }
  },
  "resources": {
    "cpu": 0,
    "memory": 268435456,
    "disk": 1073741824,
    "network": 5000000,
    "netmax": 0
  },
  "rollout": {
    "force_stop_old_instances_after": 120,
    "flapping_minimum_restarts": 3,
    "flapping_percent": 0.5,
    "flapping_window": 300,
    "errored_state_window": 0
  },
  "restart": {
    "restart_mode": "always",
    "maximum_attempts": 0
  },
  "hard_scheduling_tags": {},
  "soft_scheduling_tags": {},
  "state": "started",
  "tags": {
    "app": "staticsite"
  },
  "weight": 0,
  "version_id": 1
}
Response

A successful response contains the updated job object.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "created_at": "2015-10-15T15:59:31.417007961Z",
    "created_by": "joe.user@apcera.com",
    "fqn": "job::/test::staticsite",
    "hard_scheduling_tags": {},
    "logs": [
        {
            "channel": "job.$JOB_UUID.stdout",
            "file": "/logs/stdout.*.log"
        },
        {
            "channel": "job.$JOB_UUID.stderr",
            "file": "/logs/stderr.*.log"
        }
    ],
    "name": "staticsite",
    "num_instances": 1,
    "packages": [
        {
            "source": "user",
            "state": "unknown",
            "uuid": "f93d73e2-9047-46b2-82b5-255f12013d2f"
        },
        {
            "source": "system",
            "state": "ready",
            "uuid": "11d3244f-b9e9-4ee0-9ebe-079c082acfd4"
        },
        {
            "source": "system",
            "state": "ready",
            "uuid": "d77faf56-e38b-41e3-8280-be9c99b65992"
        },
        {
            "source": "system",
            "state": "ready",
            "uuid": "f93d73e2-9047-46b2-82b5-255f12013d2f"
        }
    ],
    "ports": [
        {
            "number": 0,
            "optional": false,
            "routes": [
                {
                    "endpoint": "staticsite.vagrant.apcera.net",
                    "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": {
        "maximum_attempts": 0,
        "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
    },
    "soft_scheduling_tags": {},
    "state": "started",
    "tags": {
        "app": "staticsite"
    },
    "updated_at": "2015-10-15T16:13:41.771604972Z",
    "updated_by": "joe.user@apcera.com",
    "uuid": "7d98c2c1-1ded-4e3c-864f-61904e97d0f0",
    "version_id": 2,
    "weight": 0
}

GET /v1/jobs/{uuid}/files

Returns a directory or file listing for a job instance. The path to the directory or file is appended to the end of the request URL. For example, /v1/jobs/{uuid}/app returns a directory listing of the instance's /app folder; /v1/jobs/{uuid}/app/index.js returns the contents index.js in the instances /app folder.

Request Parameters

Name Description Type
uuid UUID of the job. String

Examples

Example 1: The following example returns a directory listing of the instance's /logs folder.

Request
GET /v1/jobs/ff1060f7-192c-477a-99b8-9f948582913c/files/logs HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "name": "stdout.app.log",
        "size": "2138"
    },
    {
        "name": "stderr.app.log",
        "size": "0"
    }
]

Example 2: The following example returns a file listing of /logs/stdout.app.log on the specified instance:

Request
GET /v1/jobs/ff1060f7-192c-477a-99b8-9f948582913c/files/logs/stdout.app.log HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
[martini] listening on :4000
[martini] time=2015-10-15 02:54:21.352173415 +0000 UTC path=/ status=200 message="OK" user_agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.71 Safari/537.36" response_time=29.017ms

GET /v1/jobs/{uuid}/instances

Returns a list of running instances of the specified job.

Request Parameters

Name Description Type
uuid UUID of the job. String

Example

Request
GET /v1/jobs/371503a4-0c71-4c56-9f71-64eef7833112/instances HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "announced_routes": true,
        "created_time": "2015-10-15T02:53:40.376725571Z",
        "exit_code": 0,
        "exited": false,
        "failed": false,
        "host": "vagrant-046bfd16",
        "instance_manager_uuid": "73c1d458-415f-4e5c-bfc5-2ea637914bbf",
        "job_version_id": 3,
        "state": "RUNNING",
        "uuid": "9093b5b1-951e-44a1-9b2b-8ee5ab99f77a"
    },
    {
        "announced_routes": true,
        "created_time": "2015-10-15T04:39:03.666734887Z",
        "exit_code": 0,
        "exited": false,
        "failed": false,
        "host": "vagrant-786f1f0f",
        "instance_manager_uuid": "887eb315-d7de-4b66-ab32-dbd7219863bd",
        "job_version_id": 3,
        "state": "RUNNING",
        "uuid": "c540ad28-42af-4fd2-81d3-3c4a5de7a43d"
    }
]

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

Issues a stop request to a given job's specified instance.

Request Parameters

Name Description Type
uuid UUID of the job. String
instance_uuid UUID of the job instance to which the stop request should be issued. Use GET /v1/jobs/{uuid}/instances to get a list of job instances. String

Example

Request
DELETE /v1/jobs/371503a4-0c71-4c56-9f71-64eef7833112/instances/9093b5b1-951e-44a1-9b2b-8ee5ab99f77a HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Response

A successful response indicates the instance was stopped.

HTTP/1.1 200 OK

null

GET /v1/jobs/{uuid}/logs

Returns the most recent log items for the specified job.

Request Parameters

Name Description Type
uuid UUID of the job. String
lines Number of log items to return in the request. String

Example

The following example returns the last three items from the specified job's log.

Request
GET /v1/jobs/ff1060f7-192c-477a-99b8-9f948582913c/logs?lines=3 HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/octet-stream

1445097771076577502,job.ff1060f7-192c-477a-99b8-9f948582913c.stdout,[martini] time=2015-10-17 16:02:51.071653643 +0000 UTC path=/webflow/static/css/main.css status=304 message="Not Modified" user_agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.71 Safari/537.36" response_time=0.164ms
1445097768081708328,job.ff1060f7-192c-477a-99b8-9f948582913c.stdout,[martini] time=2015-10-17 16:02:48.062447618 +0000 UTC path=/webflow/static/js/webflow.js status=304 message="Not Modified" user_agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.71 Safari/537.36" response_time=0.229ms
1445097770581692264,job.ff1060f7-192c-477a-99b8-9f948582913c.stdout,[martini] time=2015-10-17 16:02:50.578876248 +0000 UTC path=/webflow/static/css/main.css status=304 message="Not Modified" user_agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.71 Safari/537.36" response_time=0.279ms

GET /v1/jobs/{uuid}/logs/drains

Returns all log drains for the specified job.

Request Parameters

Name Description Type
uuid UUID of the job. String

Example

Request
GET /v1/jobs/371503a4-0c71-4c56-9f71-64eef7833112/logs/drains HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "conf": {
            "priority": 0,
            "protocol": ""
        },
        "max_size": 2048,
        "url": "syslog://your-drain.com:1234",
        "uuid": "a2252a1d-39c3-48dc-8065-bb5009364cb3"
    },
    {
        "conf": {
            "priority": 0,
            "protocol": "udp"
        },
        "max_size": 4096,
        "url": "syslog://another-drain.com:4567",
        "uuid": "b4027016-5cdb-4eff-8303-e7e2d732a85b"
    }
]

POST /v1/jobs/{uuid}/logs/drains

Creates a log drain for the specified job.

Request Parameters

Name Description Type Parameter Type
uuid UUID of the job. String Query
POST body A log drain object. String Body

Example

Request
POST /v1/jobs/371503a4-0c71-4c56-9f71-64eef7833112/logs/drains HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

{
  "conf":{
    "priority":0,
    "protocol":"udp"
  },
  "max_size":4096,
  "url":"syslog://logs3.papertrailapp.com:4567"
}
Response
HTTP/1.1 200 OK
Content-Type: application/json

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

Deletes a log drain from a job and returns the updated job object.

Request Parameters

Name Description Type
uuid UUID of the job from which to delete the drain. String
drain_uuid UUID of the drain to delete. String

Example

Request
DELETE /v1/jobs/371503a4-0c71-4c56-9f71-64eef7833112/logs/drains/a2252a1d-39c3-48dc-8065-bb5009364cb3 HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "created_at": "2015-10-15T02:52:26.190116624Z",
    "created_by": "joe.user@apcera.com",
    "drains": [
        {
            "conf": {
                "priority": 0,
                "protocol": "udp"
            },
            "max_size": 4096,
            "url": "syslog://another-drain.com:4567",
            "uuid": "b4027016-5cdb-4eff-8303-e7e2d732a85b"
        }
    ],
    "fqn": "job::/dev::myapp",
    ...
}

POST /v1/jobs/{uuid}/networks

Joins a job to a virtual network.

Request Parameters

Name Description Type
uuid UUID of the job to join to a network. String
POST body JSON object with two fields: job_fqn and network_fqn that specify, respectively, the FQNs of the job to join to a network and the network it will join. String

Example

The following example joins the job /sandbox/admin::myapp to the network /sandbox/admin::devnet.

Request
POST /v1/jobs/305d65f1-b9be-402f-91a3-ca5583ad8932/networks HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

{
    "job_fqn":"job::/sandbox/admin::myapp",
    "network_fqn":"network::/sandbox/admin::devnet"
}
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "job_fqn": "job::/sandbox/admin::myapp",
    "network_fqn": "network::/sandbox/admin::devnet"
}

DELETE /v1/jobs/{uuid}/networks/{network_uuid}

Removes a job from a virtual network.

Request Parameters

Name Description Type
uuid UUID of the job to remove from the specified network. String
network_uuid UUID of the network from which the job should be removed. String

Example

Request
DELETE /v1/jobs/305d65f1-b9be-402f-91a3-ca5583ad8932/networks/e4893f6c-4ed1-4bca-8e7e-f3a7dd56a188 HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Response
HTTP/1.1 200 OK
Content-Length: 4
Content-Type: application/json

null

POST /v1/manifests

Deploys a multi-resource manifest that declares and configures one or more jobs, services, and networks, and links between those resources. A successful request starts an asynchronous process on the Apcera cluster that executes the manifest, creating each job, service or network declared in the manifest.

A successful response is a ManifestResponse object. The location field of the response object is the URI of a Task object you use to monitor progress of the manifest execution.

Note: In addition to location, the ManifestReponse object contains fields that are only populated in response to calling POST /v1/manifests/expansion, specifically, expanded_manifest, expanded_json, and warnings.

There are two ways to use the URI in the location field to track progress of the manifest deployment:

Request Parameters

Name Description Type
POST body JSON object that defines a multi-resource manifest. String

Example

Request
POST /v1/manifests HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

{
    "jobs": {
        "job::/sandbox/admin::testcapsule": {
            "packages": [
                {
                    "fqn": "package::/apcera/pkg/os::ubuntu-14.04-apc3"
                }
            ],
            "ssh": true,
            "start": {
                "cmd": "/sbin/init"
            },
            "state": "started"
        }
    }
}
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "location": "http://api.try.apcera.net/v1/tasks/700391fe-461e-489d-9bf0-84619d5fae2c",
  "expanded_manifest": {},
  "expanded_json": "",
  "warnings": ""
}

POST /v1/manifests/expansion

Expands substitution variables in a multi-resource manifest and returns the expanded manifest. The expanded manifest can then be deployed by calling POST /v1/manifests. A successful response is a ManifestResponse object that contains the expanded manifest, as well as any warnings that may have occurred during the expansion.

An unsuccessful response is an APIError object whose APIErrorDetails field contains the following additional fields:

Name Description Schema  
errors Errors that occurred during the manifest expansion. string  
expanded_json Expanded manifest JSON. Substitution variables that could not be substituted due to errors are left in their original form. string  
warnings Non-fatal warnings that occurred during the manifest expansion. string  

The multi-resource manifest sent in the request should contain the following additional fields:

  • variables - An object that maps substitution variables declared in the manifest to their values. For example, the following manifest contains a substitution variable named ${APP_NAME} for the job's local name that will be replaced with my-app:
    {
      "jobs": {
          "job::/sandbox/admin::${APP_NAME}": { ... }
      },
      "variables": {
          "APP_NAME": "my-app"
      }
    }
    

    After variable expansion, the expanded manifest would look like the following:

    {
        "jobs": {
            "job::/sandbox/admin::my-app": { ... }
        }
    }
    
  • default_namespace - A string that specifies the value to use for the namespace portion of an FQN that ends up empty after variable expansion. For example, consider the following manifest that declares a job with the FQN job::${MY_NAMESPACE}::app-name and sets default_namespace to "/sandbox/admin":
    {
      "jobs": {
          "job::${MY_NAMESPACE}::${APP_NAME}": { ... }
      },
      "default_namespace": "/sandbox/admin",
      "variables": {
          "APP_NAME": "my-app"
      }
    

    After variable expansion, the expanded manifest would look like the following:

    {
        "jobs": {
            "job::/sandbox/admin::app-name": { ... }
        }
    }
    

    Notes:

    • Even if no variable is used in the namespace portion of an FQN, the namespace will be replaced with the value of default_namespace. For example, if the original, unexpanded manifest contains the FQN job::::local-name, and default_namespace is set to /dev, it will be expanded to job::/dev::local-name.
    • The default_namespace variable was provided as a convenience to APC users; in APC, default_namespace is always set to APC's current namespace.

Request Parameters

Name Description Type
POST body JSON object that defines a multi-resource manifest containing substitution variables and values to substitute. String

Example

Consider the following manifest that declares three substitution variables: $NAMESPACE, $JOBNAME, AND $JOBSTATE. The variables field defines values for JOBNAME and JOBSTATE, and default_namespace is set to /sandbox/admin.

{
  "jobs": {
    "job::${NAMESPACE}::${JOBNAME}": {
      "packages": [
        {
          "fqn": "package::/apcera/pkg/os::ubuntu-14.04-apc3"
        }
      ],
      "ssh": true,
      "state": "${JOBSTATE}"
    }
  },
  "variables": {
    "JOBNAME": "myapp",
    "JOBSTATE": "started"
  },
  "default_namespace": "/sandbox/admin"
}
Request

The request contains the original (un-expanded) manifest:

POST /v1/manifests/expansion HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

{
  "jobs": {
    "job::${NAMESPACE}::${JOBNAME}": {
      "packages": [
        {
          "fqn": "package::/apcera/pkg/os::ubuntu-14.04-apc3"
        }
      ],
      "ssh": true,
      "state": "${JOBSTATE}"
    }
  },
  "variables": {
    "JOBNAME": "myapp",
    "JOBSTATE": "started"
  },
  "default_namespace": "/sandbox/admin"
}
Response

A successful response is a ManifestResponse object that contains the expanded manifest as a JSON object (expanded_manifest) and in its raw form (expanded_json). The response object's warnings indicates that it could not find a substitution value for the variable ${NAMESPACE} in the job's FQN. In this case, that warning can be ignored because the default_namespace value is used to substitute the namespace in the FQN.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "location": "",
  "expanded_manifest": {
    "jobs": {
      "job::/sandbox/admin::myapp": {
        "packages": [
          {
            "fqn": "package::/apcera/pkg/os::ubuntu-14.04-apc3"
          }
        ],
        "ssh": true,
        "state": "started"
      }
    },
    "variables": {
      "JOBNAME": "myapp",
      "JOBSTATE": "started"
    },
    "default_namespace": "/sandbox/admin"
  },
  "expanded_json": "{\n  \"jobs\": {\n    \"job::/sandbox/admin::myapp\": {\n      \"packages\": [\n        {\n          \"fqn\": \"package::/apcera/pkg/os::ubuntu-14.04-apc3\"\n        }\n      ],\n      \"ssh\": true,\n      \"state\": \"started\"\n    }\n  },\n  \"variables\": {\n    \"JOBNAME\": \"myapp\",\n    \"JOBSTATE\": \"started\"\n  },\n  \"default_namespace\": \"/sandbox/admin\"\n}",
  "warnings": "no value found for variable NAMESPACE"
}

GET /v1/namespace/default

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

Request Parameters

None.

Example

Request
GET /v1/namespace/default HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "namespace": "/sandbox/joe.smith"
}

GET /v1/networks

Returns a list of virtual networks.

Request Parameters

None.

Example

In the following example, the cluster has a single virtual network defined named net2 that has three member jobs: /sandbox/admin::myapp, /sandbox/admin::other-app, and /sandbox/admin::guide. The myapp and guide apps are running and have been assigned IP addresses, while the third (other-app) is stopped and has not been assigned an IP.

Request
GET /v1/networks HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Response
HTTP/1.1 200 OK
Content-Type: application/json

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

GET /v1/networks/{uuid}

Returns a virtual network.

Request Parameters

Name Description Type
uuid UUID of the virtual network to retrieve. String

Example

Request
GET /v1/networks/756a0784-1ff0-496d-85ef-5302525e857e HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "created_at": "2015-11-14T15:05:20.833171242Z",
    "created_by": "admin@apcera.me",
    "description": "",
    "fqn": "network::/sandbox/admin::net1",
    "name": "net1",
    "network_end_points": null,
    "subnet_info": {
        "Subnet": "192.168.2.0/24"
    },
    "updated_at": "2015-11-14T15:05:20.833171242Z",
    "updated_by": "",
    "uuid": "756a0784-1ff0-496d-85ef-5302525e857e",
    "version_id": 0
}

DELETE /v1/networks/{uuid}

Deletes a virtual network.

Request Parameters

Name Description Type
uuid UUID of the virtual network to delete. String

Example

Request
DELETE /v1/networks/756a0784-1ff0-496d-85ef-5302525e857e HTTP/1.1
api.try.apcera.net
Authorization: Bearer ...
Response
HTTP/1.1 200 OK
Content-Type: application/json

null

POST /v1/networks

Creates a new virtual network.

Request Parameters

Name Description Type
POST body The virtual network object to create. String

Example

The following example creates a new virtual network named devnet in the /sandbox/admin namespace.

Request
POST /v1/networks HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

{
  "fqn": "network::/sandbox/admin::devnet",
  "name": "devnet",
  "description": "Network for developers."
}
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "created_at": "2015-11-14T15:19:37.386190806Z",
    "created_by": "admin@apcera.me",
    "description": "Network for developers.",
    "fqn": "network::/sandbox/admin::devnet",
    "name": "devnet",
    "network_end_points": null,
    "subnet_info": {
        "Subnet": "192.168.2.0/24"
    },
    "updated_at": "2015-11-14T15:19:37.386190806Z",
    "updated_by": "",
    "uuid": "31fd55fc-79da-401f-8056-b7e703bc6488",
    "version_id": 0
}

GET /v1/packages

Returns a list of packages on the cluster.

Request Parameters

Name Description Required Schema Default
tag Returns packages with the specified comma-delimited set of tags. false array (string)  
ids Comma-separated list of UUIDs of package(s) to return. false string (string)  
name Local name of package to return. false string (string)  
fqn FQN of package to return. false string (string)  
matchPartialFQN If true, packages that partially match the specified FQN are returned. false string (boolean)  
excluded_tags Returns packages without the specified comma-delimited set of tags. false string  
provides_type Returns packages that provides dependencies that match the specified type. Valid values are os, package, runtime, or file. false string  
provides_name Returns packages that provide dependencies whose name matches the specified name. Value can be an exact package name ("java-1.6" or "ubuntu-14.04", for example) or a generalized requirement ("linux", for example). false string  

Examples

Example 1: The following example lists packages that provide dependencies that match the string "ubuntu".

Request
GET /v1/packages?provides_name=ubuntu HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response

In this case, the response includes package::/apcera/pkg/os::ubuntu-13.10 and package::/apcera/pkg/os::ubuntu-14.04.

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "created_at": "2016-03-22T20:26:06.413379481Z",
        "created_by": "admin@apcera.me",
        "environment": {
            "PATH": "$PATH:/bin:/sbin:/usr/bin:/usr/sbin"
        },
        "fqn": "package::/apcera/pkg/os::ubuntu-14.04-apc3",
        "name": "ubuntu-14.04-apc3",
        "provides": [
            {
                "name": "linux",
                "type": "os"
            },
            {
                "name": "ubuntu",
                "type": "os"
            },
            {
                "name": "ubuntu-14.04",
                "type": "os"
            },
            {
                "name": "ubuntu-14.04-apc3",
                "type": "os"
            }
        ],
        "resource": {
            "digest": "sha256:bc29011807c560414041302fb804c317ae1405194149af0803321c9d22f8cef1",
            "length": 71616527,
            "uuid": "1d94dc1d-0361-498c-95d9-b8112ed9c059"
        },
        "resources": [
            {
                "digest": "sha256:bc29011807c560414041302fb804c317ae1405194149af0803321c9d22f8cef1",
                "length": 71616527,
                "uuid": "1d94dc1d-0361-498c-95d9-b8112ed9c059"
            }
        ],
        "state": "ready",
        "updated_at": "2016-03-22T20:26:08.392506152Z",
        "updated_by": "",
        "uuid": "d45ccbfd-8fc7-43e8-8941-bf713b4ad9b6",
        "version_id": 3
    }
]

Example 2: The following returns all packages in the /sandbox namespace and sub-namespaces:

Request
GET /v1/packages?fqn=package::/sandbox&matchPartialFQN=true HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer <token>
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "created_at": "2015-10-15T01:38:03.063859373Z",
        "created_by": "user@apcera.com",
        "dependencies": [
            {
                "name": "nginx",
                "type": "package"
            }
        ],
        "environment": {
            "START_COMMAND": "./start_nginx",
            "START_PATH": "/app"
        },
        "fqn": "package::/sandbox/user::myapp",
        "name": "myapp",
        "resource": {
            "digest": "sha256:08f141d2439b194e326f697d9908721012753130ca1fa134be6bdf3f05c4784d",
            "length": 2114,
            "uuid": "f2a3987c-c2bd-4f03-858a-1d6151ccb22a"
        },
        "stager_job_fqns": [
            "job::/apcera/stagers::static-site"
        ],
        "staging_pipeline_fqn": "stagpipe::/apcera::static-site",
        "state": "ready",
        "tags": {
            "linked-job": "5df5231f-b207-47c8-8503-89db2e406b7f"
        },
        "updated_at": "2015-10-15T01:38:05.318218733Z",
        "updated_by": "user@apcera.com",
        "uuid": "aed90e91-9a98-43e2-9240-2067f0d20c80",
        "version_id": 5
    },
    {
        "created_at": "2015-10-15T01:42:24.023482686Z",
        "created_by": "user@apcera.com",
        "dependencies": [
            {
                "name": "nginx",
                "type": "package"
            }
        ],
        "environment": {
            "START_COMMAND": "./start_nginx",
            "START_PATH": "/app"
        },
        "fqn": "package::/sandbox/user::myapp-2",
        "name": "myapp-2",
        "resource": {
            "digest": "sha256:662796c97d782e69a93b628bae4e3eb835a3f2de2c0a12a152818aca9dc574e7",
            "length": 2107,
            "uuid": "2fbd89e2-7045-4c37-97af-2920bcc727ef"
        },
        "stager_job_fqns": [
            "job::/apcera/stagers::static-site"
        ],
        "staging_pipeline_fqn": "stagpipe::/apcera::static-site",
        "state": "ready",
        "tags": {
            "linked-job": "94b56a27-a908-4eb2-9096-06257dff6112"
        },
        "updated_at": "2015-10-15T01:42:28.270992965Z",
        "updated_by": "user@apcera.com",
        "uuid": "a9f343ec-6b4e-44ba-8ffa-b3da56b79786",
        "version_id": 5
    }
]

POST /v1/packages

Creates a new Package object that contains meta-data about the package, including its name, FQN, and information about the binary package resource(s) associated with the package, including the length and hash digest of each binary resource.

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 using the PUT /v1/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.

Request Parameters

Name Description Type
POST body Package object to create. String

Example

For example, the following creates the package /sandbox/admin::a_package that defines two package resources, with the specified lengths and SHA256 digests.

Request
POST /v1/packages HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

{
  "fqn": "package::/sandbox/admin::a_package",
  "name": "a_package",
  "resources": [
    {
      "digest": "sha256:fb3e36370f543779709e6a9b3e509cd814ae7f079201ce8b42a5f66415e81154",
      "length": 42
    },
    {
      "digest": "sha256:2785de71091ce5e228b8a9f97c032ea08982d9513e07d97c753c38f359c93159",
      "length": 535
    }
  ]
}
Response

A successful response is the newly created package object with an assigned uuid and its state field set to "uploading". Each package resource in the response is also assigned a UUID. You can then call PUT /v1/packages/{packageid}/resources/{resourceid} endpoint to upload each package resource.

The response's Location HTTP header is set to the new package's URI.

HTTP/1.1 200 OK
Content-Type: application/json
Location: http://api.try.apcera.net/v1/packages/f2bba743-98c6-4d0c-9a57-a601edb35107

{
  "created_at": "2017-03-06T18:48:46.615359018Z",
  "created_by": "admin@apcera.me",
  "fqn": "package::/sandbox/admin::a_package",
  "name": "a_package",
  "resource": {
    "digest": "sha256:fb3e36370f543779709e6a9b3e509cd814ae7f079201ce8b42a5f66415e81154",
    "length": 42,
    "uuid": "7cd85ea3-6dbc-4c1a-8106-ad69205c0a14"
  },
  "resources": [
    {
      "digest": "sha256:fb3e36370f543779709e6a9b3e509cd814ae7f079201ce8b42a5f66415e81154",
      "length": 42,
      "uuid": "7cd85ea3-6dbc-4c1a-8106-ad69205c0a14"
    },
    {
      "digest": "sha256:2785de71091ce5e228b8a9f97c032ea08982d9513e07d97c753c38f359c93159",
      "length": 535,
      "uuid": "8642f896-e6c2-46a9-90f6-4f1f6fdfbbd8"
    }
  ],
  "state": "uploading",
  "updated_at": "2017-03-06T18:48:46.615359018Z",
  "updated_by": "",
  "uuid": "8bc89218-9216-4c79-99ea-abb0ac35d27c",
  "version_id": 1
}

POST /v1/packages/dependencies

Returns a list of packages that fulfill the specified dependency type and name for the specified namespace or resource. The list of packages that is returned is determined by package resolution policy.

Request Parameters

Name Description Type
POST body A PackageDependsRequest object that specifies the target job, and the type and name of the dependency to resolve. String

Example

The following returns packages that satisfy dependencies for Java runtimes for jobs in in /dev namespace. In this case, package.default policy was added to the cluster that resolves "runtime.java" to the package named "openjdk-1.6":

on job::/dev {
  if (dependency equals runtime.java) {
    package.default "package::/apcera/pkg/runtimes::openjdk-1.6"
  }
}
Request
POST /v1/packages/dependencies HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

{
    "job_target": "job::/dev",
    "dependencies": [
        {
            "name": "java",
            "type": "runtime"
        }

    ]
}
Response
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "created_at": "2015-10-15T00:12:54.689962406Z",
        "created_by": "joe.user@apcera.com",
        "environment": {
            "PATH": "$PATH:/bin:/sbin:/usr/bin:/usr/sbin"
        },
        "fqn": "package::/apcera/pkg/os::ubuntu-14.04",
        "name": "ubuntu-14.04",
        "provides": [
            {
                "name": "linux",
                "type": "os"
            },
            {
                "name": "ubuntu",
                "type": "os"
            },
            {
                "name": "ubuntu-14.04",
                "type": "os"
            }
        ],
        "resource": {
            "digest": "sha1:70d826a2ad7c2f6b68b5e5a7a5e074a679773262",
            "length": 71089992,
            "sha1": "70d826a2ad7c2f6b68b5e5a7a5e074a679773262",
            "uuid": "6c01a594-b93c-48da-8cb0-e6e723ae592e"
        },
        "state": "ready",
        "updated_at": "2015-10-15T00:12:56.378288834Z",
        "updated_by": "",
        "uuid": "11d3244f-b9e9-4ee0-9ebe-079c082acfd4",
        "version_id": 2
    },
    {
        "created_at": "2015-10-15T00:12:07.46451353Z",
        "created_by": "joe.user@apcera.com",
        "dependencies": [
            {
                "name": "linux",
                "type": "os"
            }
        ],
        "environment": {
            "JAVA_HOME": "/opt/apcera/java-1.6.0-b31",
            "PATH": "/opt/apcera/java-1.6.0-b31/bin:$PATH"
        },
        "fqn": "package::/apcera/pkg/runtimes::openjdk-1.6",
        "name": "openjdk-1.6",
        "provides": [
            {
                "name": "java",
                "type": "runtime"
            },
            {
                "name": "java-1.6",
                "type": "runtime"
            },
            {
                "name": "java-1.6.0",
                "type": "runtime"
            },
            {
                "name": "java-1.6.0-b31",
                "type": "runtime"
            }
        ],
        "resource": {
            "digest": "sha1:a939564ae51a8f0e38a3c70ffab978e9baa54d95",
            "length": 65794500,
            "sha1": "a939564ae51a8f0e38a3c70ffab978e9baa54d95",
            "uuid": "2839af3c-e66f-49d0-94c5-e14af5f8abc9"
        },
        "state": "ready",
        "updated_at": "2015-10-15T00:12:09.938661914Z",
        "updated_by": "",
        "uuid": "fd7d7bd2-5c14-4667-8c85-b8947ed038fb",
        "version_id": 2
    }
]

GET /v1/packages/resources/{uuid}

Downloads the specified package's binary resource.

Request Parameters

Name Description Type
uuid UUID of the package. String

Example

Request
GET /v1/packages/resources/b58cde0e-f4f5-48f1-884f-045355abb1c6 HTTP/1.1
Host: api.vagrant.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Length: 2107
Content-Type: application/x-gzip

+-----------------------------------------+
| NOTE: binary data not shown in terminal |
+-----------------------------------------+

PUT /v1/packages/{packageid}/resources/{resourceid}

Uploads a binary resource for the specified package. The Content-Digest and Content-Length HTTP header values in the request must match the digest and length values specified for the same PackageResource in a previous call to POST /v1/packages.

Request Parameters

Name Description Type
packageid UUID of the package to update. String
resourceid UUID of the package resource to update. String

Request Headers

Name Description Type
Content-Digest A SHA-1, SHA-256, SHA-384, or SHA-512 hash of a binary package resource (TGZ file). The hash value must be prefixed with one of the following, depending on the algorithm used: sha1:, sha256:, sha384:, or sha512: (for example: sha1:3c650b19716f3fe6ca293fbf78795f45ba684ea6). String
Content-Length Length of the package resource in bytes. String

Example

The following uploads the binary for a package resource with the UUID 37EF6904-CCE8-421A-932B-905E7F2FCE49 belonging to the package with UUID B1F6925A-A5CE-4511-97CA-F37B38C762BC.

Request
PUT /v1/packages/b1f6925a-a5ce-4511-97ca-f37b38c762bc/resources/37ef6904-cce8-421a-932b-905e7f2fce49 HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Content-Length: 16
Content-Digest: sha256:c51dd4b0ec9d6b06f69f1b2559f18df93132dad2822500cf1cf2e31a8005ab76

<binary resource>
Response
HTTP/1.1 200 OK
Content-Type: application/json

null

DELETE /v1/packages/{uuid}

Deletes the specified package.

Request Parameters

Name Description Type
uuid UUID of the package to delete. String

Example

Request
DELETE /v1/packages/c6e65503-5a91-48f9-969d-16ea714a389a HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Response
HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 4
Content-Type: application/json

null

GET /v1/packages/{uuid}

Returns the specified package.

Request Parameters

Name Description Type
uuid UUID of the package to retrieve. String

Example

Request
GET /v1/packages/f700b452-fd42-4650-9e0c-0d55000ba342 HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "created_at": "2015-10-15T12:12:33.410296563Z",
    "created_by": "joe.user@apcera.com",
    "dependencies": [
        {
            "name": "nginx",
            "type": "package"
        }
    ],
    "environment": {
        "START_COMMAND": "./start_nginx",
        "START_PATH": "/app"
    },
    "fqn": "package::/sandbox/joe.user::app1",
    "name": "app1",
    "resource": {
        "digest": "sha256:ed8d266b22122ecb051b569cb0d93e41b76f5dba2f54ee4cacd3596767f1dfe2",
        "length": 2104,
        "uuid": "ed8bce06-1193-474d-8581-f2cef9a3663a"
    },
    "stager_job_fqns": [
        "job::/apcera/stagers::static-site"
    ],
    "staging_pipeline_fqn": "stagpipe::/apcera::static-site",
    "state": "ready",
    "updated_at": "2015-10-15T12:12:36.254628068Z",
    "updated_by": "staging_coordinator@apcera.me",
    "uuid": "f700b452-fd42-4650-9e0c-0d55000ba342",
    "version_id": 4
}

PUT /v1/packages/{uuid}

Updates the specified package's properties.

Request Parameters

Name Description Type
uuid UUID of the package to update. String
POST body Package object with updated properties. String

Example

The following request updates the specified package's name and fqn fields with a new package name ("new-static-site-package"):

Request
PUT /v1/packages/f700b452-fd42-4650-9e0c-0d55000ba342 HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

{
  "uuid": "f700b452-fd42-4650-9e0c-0d55000ba342",
  "name": "new-static-site-package",
  "fqn": "package::/sandbox/joe.user::new-static-site-package",
  "staging_pipeline_fqn": "stagpipe::/apcera::static-site",
  "stager_job_fqns": [
    "job::/apcera/stagers::static-site"
  ],
  "resources": [
    {
        "uuid": "ed8bce06-1193-474d-8581-f2cef9a3663a",
        "digest": "sha256:ed8d266b22122ecb051b569cb0d93e41b76f5dba2f54ee4cacd3596767f1dfe2",
        "length": 2104
    }
  ],
  "dependencies": [
    {
      "type": "package",
      "name": "nginx"
    }
  ],
  "environment": {
    "START_COMMAND": "./start_nginx",
    "START_PATH": "/app"
  },
  "state": "ready",
  "version_id": 4
}
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "created_at": "2015-10-15T12:12:33.410296563Z",
    "created_by": "joe.user@apcera.com",
    "dependencies": [
        {
            "name": "nginx",
            "type": "package"
        }
    ],
    "environment": {
        "START_COMMAND": "./start_nginx",
        "START_PATH": "/app"
    },
    "fqn": "package::/sandbox/joe.user::new-static-site-package",
    "name": "new-static-site-package",
    "resources": [
        {
            "digest": "sha256:ed8d266b22122ecb051b569cb0d93e41b76f5dba2f54ee4cacd3596767f1dfe2",
            "length": 2104,
            "uuid": "ed8bce06-1193-474d-8581-f2cef9a3663a"
        }
    ],
    "stager_job_fqns": [
        "job::/apcera/stagers::static-site"
    ],
    "staging_pipeline_fqn": "stagpipe::/apcera::static-site",
    "state": "ready",
    "updated_at": "2015-10-15T21:31:50.053342418Z",
    "updated_by": "joe.user@apcera.com",
    "uuid": "f700b452-fd42-4650-9e0c-0d55000ba342",
    "version_id": 5
}

GET /v1/policy

Returns a list of PolicyDocumentInfo objects sorted by name. To get details for a particular document, call GET /v1/policy/{name}.

Note: Policy API requests are handled by the cluster's "auth" host (auth.try.apcera.net, for example).

Request Parameters

None.

Example

Request
GET /v1/policy HTTP/1.1
Host: auth.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "docs": [
        {
            "name": "adminUsers",
            "updated_at": "2015-11-05T19:43:41.112325841Z",
            "updated_by": "system",
            "version": 1
        },
        {
            "name": "allUsersPermissions",
            "updated_at": "2015-11-05T19:43:41.122683718Z",
            "updated_by": "system",
            "version": 1
        },
        {
            "name": "docker",
            "updated_at": "2015-11-05T19:43:41.126242425Z",
            "updated_by": "system",
            "version": 1
        },
        {
            "name": "packageresolution",
            "updated_at": "2015-11-05T19:43:41.126630609Z",
            "updated_by": "system",
            "version": 1
        },
        {
            "name": "quotas",
            "updated_at": "2015-11-05T19:43:41.12446874Z",
            "updated_by": "system",
            "version": 1
        },
        {
            "name": "rolePermissions",
            "updated_at": "2015-11-05T19:43:41.124743328Z",
            "updated_by": "system",
            "version": 1
        }
    ]
}

GET /v1/policy/{name}

Returns a PolicyDocument for the named policy document. The name can only contain letters, numbers, dashes ('-'), or underscores ('_'), and cannot start with a dash ('-'). To retrieve a specific version of a policy document, specify the version with the version query parameter.

Note: Policy API requests are handled by the cluster's "auth" host (auth.try.apcera.net, for example).

Request Parameters

Name Description Type
name Name of the policy document to retrieve. String
version Version of the named policy document to retrieve. Integer

Examples

Example 1: The following example returns the contents of the policy document named quotas.

Request
GET /v1/policy/quotas HTTP/1.1
Host: auth.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
{
  "name": "quotas",
  "text": "on quota::/ {\n  { max.package.size 2GB }\n}\n",
  "version": 1,
  "updated_at": "0001-01-01T00:00:00Z"
}

Example 2: The following example returns the contents of version 2 of the policy document named quotas.

Request
GET /v1/policy/quotas?version=2 HTTP/1.1
Host: auth.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
{
  "name": "quotas",
  "text": "on quota::/ {\n  { max.package.size 2GB }\n}\n\nquota::/sandbox/demouser {\n  { max.package.size 1GB }\n  { total.package.size 6GB }\n  { total.memory 5GB }\n  { total.disk 15GB }\n  { total.network 1Gbps }\n}",
  "version": 2,
  "updated_at": "0001-01-01T00:00:00Z"
}

PUT /v1/policy

Adds or updates one or more policy documents. Takes an array of PolicyDocumentRequest objects in the request body, each of which represents an existing policy document to update or a new one to create. All documents in the request body are updated transactionally.

To update an existing policy document the for_version field of the corresponding PolicyDocumentRequest must specify the current version of the document you are updating. If the specified version is not the current version then the update will fail. It is up to the client to reconcile the document state before the next attempt. When creating a new policy document you can omit for_version from the request object, or set its value to 0.

A successful request returns the cluster's overall policy version after the update. Each successful call to this API increases the cluster's policy version by one. This is not the version associated with a particular policy document, as returned by GET /v1/policy or GET /v1/policy/{name} endpoints.

Note: Policy API requests are handled by the cluster's "auth" host (auth.try.apcera.net, for example).

Request Parameters

Name Description Type
PUT body An object with a docs field that is an array of PolicyDocumentRequest objects. String

Example

The following example updates an existing policy document named "job-policy", and creates a new document named new-policy. Also see Creating and updating policy documents in Apcera REST API Recipes.

Request
PUT /v1/policy HTTP/1.1
Host: auth.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

{
  "docs": [
    {
        "name": "packageresolution",
        "for_version": 3,
        "text": "on job::/ {\n  // For package dependency resolution.\n  { package.allow \"package::/apcera\" }\n\n  if (dependency equals os.linux) {\n    package.default \"package::/apcera/pkg/os::ubuntu-14.04-apc3\"\n  }\n  if (dependency equals os.ubuntu) {\n    package.default \"package::/apcera/pkg/os::ubuntu-14.04-apc3\"\n  }\n  if (dependency equals runtime.ruby) {\n    // package.default \"package::/apcera/pkg/runtimes::ruby-2.2.4\"\n    package.default \"package::/apcera/pkg/runtimes::ruby-1.9.3-p547\"\n  }\n  if (dependency equals runtime.perl) {\n    package.default \"package::/apcera/pkg/runtimes::perl-5.22.1\"\n  }\n  if (dependency equals runtime.java) {\n    package.default \"package::/apcera/pkg/runtimes::openjdk-1.8\"\n  }\n  if (dependency equals runtime.node) {\n    package.default \"package::/apcera/pkg/runtimes::node-4.4.6\"\n  }\n  if (dependency equals runtime.go) {\n    package.default \"package::/apcera/pkg/runtimes::go-1.6\"\n  }\n}\n\n// job::/sandbox/lparis {\n//   if (dependency equals runtime.java) \n//   {\n//     package.retire \"package::/apcera/pkg/runtimes::openjdk-1.6\"\n//   }\n// }\n"
    },
    {
        "name": "new-policy",
        "text": "<continuum-policy description=\"Sample Solution: Requirement 4\">\n\non all::/sandbox/[name] {\n    if (auth_server@apcera.me->name == [name] && query->target fqnMatch \"*::/sandbox/[name]\") {\n        permit all\n    }\n}"
    }
  ]
}
Response

The response indicates that the cluster is currently on policy version 3212.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "version": 3212
}

DELETE /v1/policy

Deletes one or more policy documents from the cluster and returns the cluster's updated policy version number. Each successful call to this API increases the policy's version number by one.

Note: Policy API requests are handled by the cluster's "auth" host (auth.try.apcera.net, for example).

Request Parameters

Name Description Type
doc Specifies one or more policy documents to delete. String

Example

The following example deletes the policy documents named "packageDocument" and "jobDocument".

Request
DELETE /v1/policy?doc=packageDocument&jobDocument HTTP/1.1
Host: auth.try.apcera.net
Authorization: Bearer ...
Response
HTTP/1.1 200 OK
Content-Length: 13
Content-Type: application/json

{
    "version": 6
}

GET /v1/providers

Returns a list of providers available on the cluster.

Request Parameters

Name Description Type
name Description…. String

Example

Request
GET /v1/providers HTTP/1.1
Host: api.bagel.buffalo.im
Authorization: Bearer ...
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "created_at": "2014-11-25T19:20:32.087954895Z",
        "created_by": "",
        "description": "",
        "fqn": "provider::/apcera/providers::mysql",
        "name": "",
        "type": "mysql",
        "uuid": "02bf9cd3-7dd6-444b-8de8-c9c594d06db6"
    },
    {
        "created_at": "2014-09-18T19:13:46.632301919Z",
        "created_by": "",
        "description": "",
        "fqn": "provider::/apcera/providers::postgres",
        "name": "",
        "type": "postgres",
        "uuid": "0ee194a9-e020-4fed-91c0-2a81e5c577aa"
    },
    {
        "created_at": "2015-03-04T01:18:06.90176187Z",
        "created_by": "",
        "description": "",
        "fqn": "provider::/apcera::ipm",
        "name": "",
        "type": "ipm",
        "uuid": "d03314a3-80ec-4f20-9000-9beafc01512a"
    }
]

POST /v1/providers

Creates a new provider.

Request Parameters

Name Description Type
POST body A provider object. String

Example

The following example creates a new PostgreSQL provider named postgres-provider from an existing job named postgres-app.

Request
POST /v1/providers HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

{
  "backing_job_fqn":"job::/dev::postgres-app",
  "backing_job_port":"5432",
  "description":"",
  "fqn":"provider::/providers::postgres-provider",
  "name":"postgres-provider",
  "parameters":{
    "url":"postgres://postgres:postgres@postgres-app"
  },
  "type":"postgres"
}
Response
HTTP/1.1 200 OK
Content-Type: application/json
Location: http://api.try.apcera.net/v1/providersbdbd4ed1-4ec4-42f9-84f2-c60b42ed703e

{
    "backing_job_fqn": "job::/dev::postgres-app",
    "backing_job_port": "5432",
    "created_at": "2015-10-16T01:55:41.345345178Z",
    "created_by": "joe.user@apcera.com",
    "description": "",
    "fqn": "provider::/test::postgres-provider",
    "name": "postgres-provider",
    "type": "postgres",
    "uuid": "bdbd4ed1-4ec4-42f9-84f2-c60b42ed703e"
}

DELETE /v1/providers/{uuid}

Deletes the specified provider.

Request Parameters

Name Description Type
uuid UUID of the provider to delete. String

Example

Request
DELETE /v1/providers/8199a158-5d56-4dbb-9238-34103d212d92 HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Response
HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 4
Content-Type: application/json

null

GET /v1/rules

Lists all semantic pipeline rules.

Request Parameters

None.

Example

Request
GET /v1/rules HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "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 /v1/rules

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

Request Parameters

Name Description Type
POST body A semantic pipeline rule object. String

Example

The following example creates a new rule name "postgres-denydelete" that denies all delete operations on the Postgres database instance represented by the service::/providers::cust-db service.

Request
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

{
  "action":{
    "commands":[
      "delete"
    ],
    "inline":"deny"
  },
  "created_at":"0001-01-01T00:00:00Z",
  "created_by":"",
  "fqn":"sempiperule::/providers::postgres-denydelete",
  "job":null,
  "name":"postgres-denydelete",
  "provider":null,
  "service":"service::/providers::cust-db",
  "type":0,
  "uuid":"",
  "version_id":0
}
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "action":{
    "commands":[
      "delete"
    ],
    "inline":"deny"
  },
  "created_at":"2015-10-16T02:29:32.746595806Z",
  "created_by":"tim.statler@apcera.com",
  "fqn":"sempiperule::/providers::postgres-denydelete",
  "job":null,
  "name":"postgres-denydelete",
  "provider":null,
  "service":"service::/providers::cust-db",
  "type":0,
  "uuid":"42dd1179-5c1e-47fd-8000-b329713e612c",
  "version_id":1
}

DELETE /v1/rules/{uuid}

Deletes a semantic pipeline event rule.

Request Parameters

Name Description Type
uuid UUID of the rule to delete. String

Example

Request
DELETE /v1/rules/c0a99ed6-ce62-4fd0-9531-344e8266ba83 HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Response
HTTP/1.1 200 OK
Content-Length: 4
Content-Type: application/json

null

GET /v1/rules/{uuid}

Returns information about a semantic pipeline rule.

Request Parameters

Name Description Type
uuid UUID of the rule to retrieve. String

Example

Request
GET /v1/rules/5d267d66-c0ce-4245-90de-4591dbb9a5f2 HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "action": {
        "commands": [
            "delete"
        ],
        "inline": "deny"
    },
    "created_at": "2015-10-16T04:50:57.322815516Z",
    "created_by": "joe.user@apcera.com",
    "fqn": "sempiperule::/sandbox/joe.user::denydelete-PG",
    "job": null,
    "name": "denydelete-PG",
    "provider": null,
    "service": "service::/providers::cust-db",
    "type": 0,
    "uuid": "5d267d66-c0ce-4245-90de-4591dbb9a5f2",
    "version_id": 1
}

GET /v1/runtimes

Lists available workload runtimes. This API is used by APC and other API clients to determine the appropriate staging pipeline to stage a given application workload. The runtime field of each response item corresponds to the name of one of the built-in staging pipelines.

Request Parameters

None.

Example

Request
GET /v1/runtimes HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Response
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "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"
    }
]

GET /v1/services

Lists available services.

Request Parameters

None.

Example

Request
GET /v1/services HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Response

Note: Number of items in example response abbreviated for readability.

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "created_at": "2015-10-15T00:07:24.690477526Z",
        "created_by": "stagehand@apcera.me",
        "description": "",
        "fqn": "service::/apcera::http",
        "name": "http",
        "provider_fqn": null,
        "type": "http",
        "uuid": "443dda0c-5fd8-44d3-9946-2988ef66911d"
    },
    {
        "created_at": "2015-10-15T00:07:40.068061294Z",
        "created_by": "stagehand@apcera.me",
        "description": "Continuum network service to outside package sources for bash",
        "fqn": "service::/apcera::bash-package-sources",
        "name": "bash-package-sources",
        "parameters": {
            "ipnet": "any",
            "portrange": "all",
            "protocol": "tcp"
        },
        "provider_fqn": null,
        "type": "network",
        "uuid": "2dd826ce-efb5-4b19-95e7-4f256662a4af"
    },
    {
        "created_at": "2015-10-16T02:26:46.236173927Z",
        "created_by": "tim.statler@apcera.com",
        "description": "",
        "fqn": "service::/providers::cust-db",
        "name": "cust-db",
        "provider_fqn": "provider::/providers::postgres-provider",
        "type": "postgres",
        "uuid": "3d0be656-9a87-44ca-83f0-77bf087e045d"
    }
]

POST /v1/services

Creates a new service.

Request Parameters

Name Description Type
POST body A service object. String

Example

The following example creates a network service named mynet-service, passing it parameters for domainname, portrange, and protocol.

Request
POST /v1/services HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

{
  "description":"Network service",
  "fqn":"service::/sandbox/admin::mynet-service",
  "name":"mynet-service",
  "type":"network",
  "parameters": {
    "domainname": "www.apcera.com",
    "portrange": "80",
    "protocol": "tcp"
  }
}
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "uuid": "94f27cb9-5145-4a7b-8916-c6ec4e97dcd4",
  "fqn": "service::/sandbox/admin::mynet-service",
  "provider_fqn": null,
  "type": "network",
  "name": "mynet-service",
  "description": "Network service",
  "created_by": "admin@apcera.me",
  "created_at": "2017-03-01T20:02:52.138838976Z",
  "parameters": {
    "domainname": "www.apcera.com",
    "portrange": "80",
    "protocol": "tcp"
  },
  "status": "created",
  "extended_status": {}
}

DELETE /v1/services/{uuid}

Deletes the specified service.

Request Parameters

Name Description Type
uuid UUID of the service to delete. String

Example

Request
DELETE /v1/services/caa5ab26-523c-497f-82db-4933bf221cb6 HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Response
HTTP/1.1 200 OK
Content-Length: 4
Content-Type: application/json

null

GET /v1/sim

Runs a policy simulation against the policies in the existing system and returns a PolicySimResponse. The requesting user must have permit read access on all realms specified in the simulation command, as well as on any realms returned in the response.

Rules for quoting values:

  • Only use quotes if the value (the item on the right-hand side of the equals sign) contains spaces (name="tim s", for example). Quotes are not allowed on the left-hand side of the equals sign.
  • Do not quote the entire parameter string (for example, input="Google->email=fred@apcera.com" is invalid).

Also see Policy Simulation for information on using APC to run simulations.

Request Parameters

Name Description Type Required
claim A claim type (permit, for example) and an optional claim value (update, for example) to filter simulation results (for example permit=create or permit). If a claim type is provided but no claim value then all matching claims are returned regardless of value. May occur multiple times in a request. String No.
fqn The realm FQN to use for the simulation. May occur multiple times in the request. Defaults to *::/ (any resource) if not specified. String No.
input An input claim that establishes user identity and other predefined claims for the simulation (for example, name=bob, Google->email=bob@gmail.com, and ResType=gateway). String No.
why Indicates whether or not to run a hypothetical analysis of claims required to satisfy access to the specified FQN with the claim type(s) and claim value(s) specified. Default is false. Boolean No.

Example

The following example runs an hypothetical policy simulation (why=true) on the FQN job::/sandbox/john with an input claim of name=jane and claim type and value of permit=create. This simulation answers the question: What permissions is the user jane missing to create jobs in the user john's sandbox namespace (/sandbox/john). In this case, jane needs a role=admin claim added to the policy document named "rollPermissions".

Request
GET /v1/sim?fqn=job::/sandbox/john&input=name=jane&claim=permit=create&why=true HTTP/1.1
Host: api.example.com
Authorization: Bearer ...
Response
HTTP/1.1 200 OK
Content-Length: 4
Content-Type: application/json

{
    "lines": [
        {
            "context": "(s) clusterPermissions.pol:11",
            "level": 0,
            "type": 0,
            "value": "permit create"
        },
        {
            "context": "(s) clusterPermissions.pol:9",
            "level": 1,
            "type": 3,
            "value": "job::/"
        },
        {
            "context": "(s) clusterPermissions.pol:10",
            "level": 1,
            "type": 1,
            "value": "(permit == all)"
        },
        {
            "context": "ADD INPUT",
            "level": 2,
            "type": 2,
            "value": "permit all"
        },
        {
            "context": "(s) rolePermissions.pol:8",
            "level": 2,
            "type": 0,
            "value": "permit all"
        },
        {
            "context": "(s) rolePermissions.pol:7",
            "level": 3,
            "type": 3,
            "value": "job::/"
        },
        {
            "context": "(s) rolePermissions.pol:8",
            "level": 3,
            "type": 1,
            "value": "(role == \"admin\")"
        },
        {
            "context": "ADD INPUT",
            "level": 4,
            "type": 2,
            "value": "role \"admin\""
        }
    ],
    "maxc": 29,
    "maxl": 4,
    "maxv": 17
}

PUT /v1/sim

Runs a policy simulation against the policies in the existing system, and ones you provide as input in the request body. If the name of a policy document does not match an existing policy document then it is added to the list of policy documents for the simulation. If there is a match, then the provided policy replaces the existing policies. Policy documents provided as input are only used for the simulation and are not saved on the cluster.

The requesting user must have permit read access on all realms specified in the simulation command, as well as on any realms returned in the response.

Rules for quoting values:

  • Only use quotes if the value (the item on the right-hand side of the equals sign) contains spaces (name="tim s", for example). Quotes are not allowed on the left-hand side of the equals sign.
  • Do not quote the entire parameter string (for example, input="Google->email=fred@apcera.com" is invalid).

Request Parameters

Name Description Type Required
PUT body A JSON object with a docs field that contains one or more named PolicySimDocumentInput objects that define policy documents add to the simulation, or to replace existing policy documents. String No
claim A claim type (permit, for example) and an optional claim value (update, for example) to filter simulation results (for example permit=create or permit). If a claim type is provided but no claim value then all matching claims are returned regardless of value. May occur multiple times in a request. String No.
fqn The realm FQN to use for the simulation. May occur multiple times in the request. Defaults to *::/ (any resource) if not specified. String No.
input An input claim that establishes user identity and other predefined claims for the simulation (for example, name=bob, Google->email=bob@gmail.com, and ResType=gateway). May occur multiple times in a request. String No.
why Indicates whether or not to run a hypothetical analysis of claims required to satisfy access to the specified FQN with the claim type(s) and claim value(s) specified. Default is false. Boolean No.

Example

The following example runs an hypothetical policy simulation (why=true) on the FQN job::/sandbox/john with an input claim of name=jane and claim type and value of permit=create, and also injects the following policy into the simulation:

on job::/sandbox/tim {
    { permit create }
}
Request
PUT /v1/sim?fqn=job::/sandbox/tim&input=name=tim&claim=permit=create&why=true HTTP/1.1
Host: auth.example.com
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiIiLCJhbGciOiIifQ...

{
    "docs": [
        {
            "name": "testpolicy",
            "text": "on job::/sandbox/tim {{ permit create }}"
        }
    ]
}
Response
HTTP/1.1 200 OK
Content-Length: 4
Content-Type: application/json

{
    "lines": [
        {
            "context": "(s) clusterPermissions.pol:11",
            "level": 0,
            "type": 0,
            "value": "permit create"
        },
        {
            "context": "(s) clusterPermissions.pol:9",
            "level": 1,
            "type": 3,
            "value": "job::/"
        },
        {
            "context": "(s) clusterPermissions.pol:10",
            "level": 1,
            "type": 1,
            "value": "(permit == all)"
        },
        {
            "context": "ADD INPUT",
            "level": 2,
            "type": 2,
            "value": "permit all"
        },
        {
            "context": "(s) rolePermissions.pol:8",
            "level": 2,
            "type": 0,
            "value": "permit all"
        },
        {
            "context": "(s) rolePermissions.pol:7",
            "level": 3,
            "type": 3,
            "value": "job::/"
        },
        {
            "context": "(s) rolePermissions.pol:8",
            "level": 3,
            "type": 1,
            "value": "(role == \"admin\")"
        },
        {
            "context": "ADD INPUT",
            "level": 4,
            "type": 2,
            "value": "role \"admin\""
        }
    ],
    "maxc": 29,
    "maxl": 4,
    "maxv": 17
}

GET /v1/stagingpipelines

Lists all staging pipelines.

Request Parameters

Name Description Type
fqn FQN of staging pipelines to return. String
matchPartialFQN If true, staging pipelines that partially match the specified FQN are returned. Default is false. Boolean

Example

The following example requests all staging pipelines in the /dev/stagingpipelines namespace.

Request
GET /v1/stagingpipelines?fqn=stagpipe::/dev/stagingpipelines&matchPartialFQN=true HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Response
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "auto_id": 0,
        "created_at": "2015-10-16T09:16:31.865506117Z",
        "created_by": "joe.user@apcera.com",
        "fqn": "stagpipe::/dev/stagingpipelines::jekyll",
        "name": "jekyll",
        "stagers": [
            {
                "uuid": "e6b42089-119b-4de7-9509-d8cdeee6632e"
            }
        ],
        "updated_at": "2015-10-16T09:16:31.865506117Z",
        "updated_by": "",
        "uuid": "0c5ffebb-f522-4f67-80bb-0caef1fd4b7c",
        "version_id": 1
    }
]

POST /v1/stagingpipelines

Creates a new staging pipeline. A staging pipeline consists of one or more stagers (jobs) that perform the actual staging operations, which are specified by their UUIDs in the request object's stagers array.

Request Parameters

Name Description Type
POST body A staging pipeline object. String

Example

The following example creates a new staging pipeline named "jekyll" in the /dev/stagingpipelines namespace. The staging pipeline comprises a single stager job (created previously).

Request
POST /v1/stagingpipelines HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

{
  "fqn":"stagpipe::/dev/stagingpipelines::jekyll",
  "name":"jekyll",
  "stagers":[
    {
      "uuid":"e6b42089-119b-4de7-9509-d8cdeee6632e"
    }
  ]
}
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "auto_id": 0,
    "created_at": "2015-10-16T09:16:31.865506117Z",
    "created_by": "joe.user@apcera.com",
    "fqn": "stagpipe::/dev/stagingpipelines::jekyll",
    "name": "jekyll",
    "stagers": [
        {
            "uuid": "e6b42089-119b-4de7-9509-d8cdeee6632e"
        }
    ],
    "updated_at": "2015-10-16T09:16:31.865506117Z",
    "updated_by": "",
    "uuid": "0c5ffebb-f522-4f67-80bb-0caef1fd4b7c",
    "version_id": 1
}

DELETE /v1/stagingpipelines/{uuid}

Deletes the specified staging pipeline.

Request Parameters

Name Description Type
uuid UUID of the staging pipeline to delete. String

Example

Request
DELETE /v1/stagingpipelines/9c585533-eeaa-4ca9-91ca-31e72a350e42 HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Response
HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 4

null

GET /v1/stagingpipelines/{uuid}

Retrieves the specified staging pipeline.

Request Parameters

Name Description Type
uuid UUID of the staging pipeline to delete. String

Example

Request
GET /v1/stagingpipelines/0c5ffebb-f522-4f67-80bb-0caef1fd4b7c HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Response
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "auto_id": 0,
        "created_at": "2015-10-16T09:16:31.865506117Z",
        "created_by": "joe.user@apcera.com",
        "fqn": "stagpipe::/dev/stagingpipelines::jekyll",
        "name": "jekyll",
        "stagers": [
            {
                "uuid": "e6b42089-119b-4de7-9509-d8cdeee6632e"
            }
        ],
        "updated_at": "2015-10-16T09:16:31.865506117Z",
        "updated_by": "",
        "uuid": "0c5ffebb-f522-4f67-80bb-0caef1fd4b7c",
        "version_id": 1
    }
]

PUT /v1/stagingpipelines/{uuid}

Updates the specified staging pipeline.

Request Parameters

Name Description Type
uuid UUID of the staging pipeline to update. String
POST body Staging pipeline object with updated properties. String

Example

The following request updates the name and FQN of the specified staging pipeline.

Request
PUT /v1/stagingpipelines/0c5ffebb-f522-4f67-80bb-0caef1fd4b7c HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

{
    "name": "jekyll-pipeline",
    "uuid": "0c5ffebb-f522-4f67-80bb-0caef1fd4b7c",
    "fqn": "stagpipe::/dev/stagingpipelines::jekyll-pipeline",
    "stagers": [
      {
        "uuid": "e6b42089-119b-4de7-9509-d8cdeee6632e"
      }
    ],
    "auto_id": 0,
    "version_id": 1
}
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "auto_id": 0,
    "created_at": "2015-10-16T09:16:31.865506117Z",
    "created_by": "joe.user@apcera.com",
    "fqn": "stagpipe::/dev/stagingpipelines::jekyll-pipeline",
    "name": "jekyll-pipeline",
    "stagers": [
        {
            "uuid": "e6b42089-119b-4de7-9509-d8cdeee6632e"
        }
    ],
    "updated_at": "2015-10-16T22:23:51.523052056Z",
    "updated_by": "joe.user@apcera.com",
    "uuid": "0c5ffebb-f522-4f67-80bb-0caef1fd4b7c",
    "version_id": 2
}

GET /v1/tags

Lists all tags on all instance managers in the cluster.

Request Parameters

None.

Example

Request
GET /v1/tags HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "NumManagers": 2,
        "Tag": "unknown"
    },
    {
        "NumManagers": 1,
        "Tag": "host-046bfd16"
    },
    {
        "NumManagers": 1,
        "Tag": "host-786f1f0f"
    }
]

GET /v1/tasks/{uuid}

Used to track the progress of an asynchronous API operation such as creating an app from a Docker image, or executing an multi-resource manifest. This endpoint is returned in the response to a call to POST /v1/jobs/docker or POST /v1/manifests. There are two ways a client can use this URL:

Request Parameters

Name Description Type
uuid UUID of task. String
time If specified, only task events that occurred after the specified time are returned. If not specified, all task events are returned. Time is in UNIX nanoseconds. Number

Examples

See Tracking progress of asynchronous API calls in Apcera REST API Recipes for details on polling and streaming tasks using this endpoint.

POST /v1/unbind

Removes a binding between a job and a service. To create a service binding, use the POST /v1/bindings API.

Request Parameters

Name Description Type
POST body Object that specifies the FQNs of the service and job to unbind. String

Example

The following example unbinds job::/dev/sandbox::customer-app and service::/dev/services::customer-db.

Request
POST /v1/unbind HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

{
    "job": "job::/dev/sandbox::customer-app",
    "service": "service::/dev/services::customer-db"
}
Response
HTTP/1.1 200 OK
Content-Type: application/json

POST /v1/unlink

Removes a link between two jobs. To create a job link, use the POST /v1/bindings API.

Request Parameters

Name Description Type
POST body Object that specifies the FQNs of the two jobs to unlink and the port where the link was established. String

Example

Request
POST /v1/unlink HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json

{
    "from_job":  "job::/sandbox/tim.statler::app1",
    "to_job":    "job::/sandbox/tim.statler::app2",
    "port":      0
}
Response
HTTP/1.1 200 OK
Connection: keep-alive

GET /v1/version

Returns the cluster version number.

Example

Request
GET /v1/version HTTP/1.1
Host: api.try.apcera.net
Authorization: Bearer ...
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "build_number": "440b"
}