Apcera REST API Model Objects

This document describes the JSON objects used by the Apcera REST API to represent resources and objects.

APIError

Returned when Apcera encounters an error handling an API request. The object's error_details field may or may not be present, depending on the API endpoint that returned the error.

Name Description Schema
client_side If true, the error was due to a client-side error (e.g., invalid data); otherwise, the error was due to a server-side error (e.g. a NATS timeout). boolean
code HTTP response status code. integer
duplicate_key If true, the resource that's being created already exists. boolean
error_details Object that provides details about the error. APIErrorDetails
fatal If true, the action was fatal and should not be retried. boolean
message Message describing the error. string
missing_claims A list of missing policy claim(s) on policy denials. string
policy_error An object that describes policy-related errors that occurred when creating or updating a job. PolicyError
request_id ID of the NATS message or HTTP request that generated the error. This value can be correlated with the Apcera component logs to further diagnose the error. string
request_invalid If true, the request cannot be processed due to a conflict. boolean
requires_restart If true, the targeted resource is in a state where the request cannot be fulfilled; for instance, a job in the started state may not have its resources changed. boolean
resource_missing If true, the requested resource could not be located. boolean
retry If true, the problem encountered was transient, and the same payload can be delivered again. boolean
token_invalid If true, the requestor's token was invalid (e.g., due to a timeout.) boolean
try_again_in_ms Specifies in milliseconds how long the client should wait before retrying the request. integer

APIErrorDetails

Represents an APIError object's error_details field. In addition to the fields listed below, this object may contain additional fields that provide details about the error.

Name Description Schema
Error Error description. string
Type Internal error type. string

AuditLogItem

Represents items returned by GET /v1/audit.

Name Description Required Schema  
audit_payload Contains additional structured data for the audit log item. false AuditLogPayload  
event_type Event type. false string  
event_type_int Integer used as the index of an enumeration of human-readable event types (see event_type). false integer (int32)  
fqn Fully-qualified name of the resource on which the auditable action was attempted. false string  
localname Local name of the resource on which the auditable action was attempted. false string  
namespace Namespace of the resource on which the auditable action was attempted. false string  
on_behalf_of Username on whose behalf the auditable action was attempted by principal_name. false string  
principal_name The actor (API Server or Health Manager, for example) or user that attempted the auditable action. false string  
resource_type The resource type on which the auditable action was attempted. false string  
timestamp UNIX timestamp that indicates when the event occurred. false number (float)  
uuid Unique identifier for the audit log entry. false string  

AuditClaimPayload

The audit_payload field for AuditLogItem objects with the event type policy.access.allowed or policy.access.denied. Consists of an object named claim that contains two fields named claimtype and claimvalue. These fields contain, respectively, the policy claim type (for example, "permit") and claim value (for example, "read") that generated the log item for the specified resource.

For example, the following policy.access.allowed audit log item was generated in response to a request for the job::/apcera::continuum-guide resource on behalf of the admin@apcera.me user. Specifically, a permit read claim type and value was checked before allowing read access to the resource. For example, this would occur anytime a user shows that job in the Web Console or using APC.

{
    "uuid": "88d1b911-a605-11e6-bbf1-08002748ca70",
    "event_type_int": 1007,
    "event_type": "policy.access.allowed",
    "fqn": "job::/apcera::continuum-guide",
    "localname": "continuum-guide",
    "namespace": "/apcera",
    "on_behalf_of": "admin@apcera.me",
    "audit_payload": {
      "claim": {
        "claimtype": "permit",
        "claimvalue": "read"
      }
    },
    "principal_name": "admin@apcera.me",
    "resource_type": "job",
    "timestamp": 1478645338
}
Name Description Schema  
claim An object with two fields: claimtype and claimvalue. object  
claimtype The claim type (permit, for example) used in the access request. string  
claimvalue The claim value ((update, for example) used in the access request. string  

AuditPatchPayload

The audit_payload field for AuditLogItem objects that represents changes to a resource's JSON representation. Consists of a patches field that is an array of JSON Patch objects that describe changes made to the specified resource. Every JSON Patch object specifies an operation, the path to the modified JSON field, the field's new value.

The Apcera audit log system supports the following subset of JSON Patch operations:

  • "add" – Indicates a new field at the specified path and with the specified value was added to the resource's JSON representation. For example, the following JSON Patch object represents the addition of a network_ref/uuid field a job resource (not shown) when the job was joined to a virtual network:

      {
        "op": "add",
        "path": "network_ref/uuid",
        "value": "e9a76724-d5c3-4a51-9fb0-8b5e70a82018
      }
    
  • "remove" – Indicates a field at the specified path and with the specified value was removed from the resource's JSON representation. For example, the following payload represents the removal of the job/labels/mylabel field from a job resource (not shown):

      {
        "op": "remove",
        "path": "job/labels/mylabel",
        "value": "foobar"
      }
    
  • "replace"– Indicates that the value of the field at the specified path was changed from value to oldvalue. For example, the following payload represents the change to the number of requested instances for a job resource (not shown):

     {
       "op": "replace",
       "path": "job/num_instances",
       "value": 2,
       "oldvalue": 1
     }
    

The following audit log item payload contains both "remove" and "replace" operations corresponding to SSH access being removed from the corresponding job (for example, by running apc app update my-app --remove-ssh). The payload shows that the job object's job/ports/number, job/ports/optional, and job/tags/ssh fields were removed from the job definition, while the job/updated_at and job/version_id job fields were updated with new values.

{
  "patches": [
    {
      "op": "remove",
      "path": "job/ports/number",
      "value": 222
    },
    {
      "op": "remove",
      "path": "job/ports/optional",
      "value": true
    },
    {
      "op": "remove",
      "path": "job/tags/ssh",
      "value": "true"
    },
    {
      "op": "replace",
      "path": "job/updated_at",
      "value": "2016-10-31T21:49:31.855140279Z",
      "oldvalue": "2016-10-31T20:24:35.09082864Z"
    },
    {
      "op": "replace",
      "path": "job/version_id",
      "value": 3,
      "oldvalue": 2
    }
  ]
}
Name Description Schema  
patches An array of JSON Patch objects that describe the changes made to the specified resource. object  

AuditLogPayload

Represents an AuditLogItem object's audit_payload field that provides additional information about the logged item. Not all audit log items have a payload.

  • For audit log items that describe changes to a resource (for instance, updating a job definition), the payload is a AuditPatchPayload object that contains an array of JSON Patch objects that describe the changes made to the resource's JSON representation.
  • For policy.access.allowed and policy.access.denied audit log event types, the payload is a AuditClaimPayload object that contains the policy claim type (for example, "permit") and claim value (for example, "update") that generated the audit access log item.

For example, below is an example AuditLogItem that describes a change made to the specified job (job::/sandbox/admin::myapp) when it was joined to a virtual network. The item's audit_payload.patches array contains a single JSON Patch object whose path field indicates the location and name of the newly added field on the Job object's JSON representation. Specifically, it shows a network_ref/uuid field was added to the Job object definition with the value 003e54ea-e5dd-4e7d-9adb-c2c40f12dd82, which is the UUID of the VirtualNetwork that the job joined.

{
  "uuid": "43ad594a-9bd6-11e6-a515-06bc450cb24a",
  "event_type_int": 6002,
  "event_type": "network.join",
  "fqn": "job::/sandbox/admin::myapp",
  "localname": "myapp",
  "namespace": "/sandbox/admin",
  "on_behalf_of": "admin@apcera.me",
  "audit_payload": {
    "patches": [
      {
        "op": "add",
        "path": "network_ref/uuid",
        "value": "003e54ea-e5dd-4e7d-9adb-c2c40f12dd82"
      }
    ]
  },
  "principal_name": "api_server@apcera.me",
  "resource_type": "job",
  "timestamp": 1477525524
}

And the following audit log item is for a policy.access.allowed event generated in response to a request for the job::/apcera::continuum-guide resource on behalf of the admin@apcera.me user. Specifically, a permit read claim type and value was checked before allowing read access to the resource. For example, this would occur anytime a user shows that job in the Web Console or using APC.

{
    "uuid": "88d1b911-a605-11e6-bbf1-08002748ca70",
    "event_type_int": 1007,
    "event_type": "policy.access.allowed",
    "fqn": "job::/apcera::continuum-guide",
    "localname": "continuum-guide",
    "namespace": "/apcera",
    "on_behalf_of": "admin@apcera.me",
    "audit_payload": {
      "claim": {
        "claimtype": "permit",
        "claimvalue": "read"
      }
    },
    "principal_name": "admin@apcera.me",
    "resource_type": "job",
    "timestamp": 1478645338
}

Binding

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

Name Description Required Schema  
name The base name of the binding. false string  
uuid The binding's unique identifier. false string  
fqn The binding's fully-qualified name of the form binding::/namespace::GUID, where GUID is a unique GUID that you generate. false string  
job_fqn Fully-qualified name of the job that is bound to another job or service. false string  
env_var List of environment variables generated for the binding. false string array  
parameters A key-value mapping of binding parameters. false object  
provider_fqn Fully-qualified name of the provider used to create the service to which the source job is bound. Only relevant for job-to-service bindings. false string  
service_fqn Fully-qualified name of a the service to which the source job is bound. Only relevant for for job-to-service bindings. false string  
target_job_fqn Fully-qualified name of the job to which the source job wants to bind (input only). false string  
target_job_uuid UUID of the job to which the source job is bound (output only). false string  
target_job_port Port on the target job that the source job wants to bind to. false string  
target_job_bound_ip IP address where the connection to the target job should be exposed. false string  
target_job_bound_port Port that the target job should be exposed at. false string  

CreateDockerJobRequest

An object that's passed to POST /v1/jobs/docker to create a job from a Docker image.

Name Description Required Schema  
allow_egress If true, the job is allowed outbound network connectivity. false boolean  
env Map of environment variable names to values to assign to each job instance. false object  
exposed_ports An array of ports exposed on job instances. false integer(array)  
group Group to run Docker image as (default: picked by Apcera). false string  
hard_scheduling_tags List of hard scheduling tags. See Hard Tags for more information. false object  
ignore_volumes If true, volumes specified in the Docker image spec are ignored and no data will be persisted. false boolean  
image_url Full Docker image URL, including image tag (https://registry-1.docker.io/library/mysql:5.5.50 or https://registry-1.docker.io/library/mysql:latest for example). For private Docker repositories, include the username and password in the image URL (https://username:password@myregistry.example.com/library/mysql:latest). true string  
interactive If true, the start command is removed from the job definition. The start command string is saved to the DOCKER_START_COMMAND environment variable on the job's environment. false boolean  
job_fqn The fully-qualified name of the job to create from the Docker image. false string  
resources A list of compute and network resources that the job can consume. false object  
restart Configuration related to restarting the job. false object  
routes A map of routes to the ports where the routes are available. false object  
soft_scheduling_tags List of soft scheduling tags. See Soft Tags for more information. false object  
start If true the job is started after its created. Default is false. false boolean  
start_command The command used to start the process, specified as an array. The first element in the array is the command/binary to execute, and subsequent array elements are command arguments. The expanded command string is passed directly to exec() without shell or template interpretation. false string(array)  
stop_command The command used to stop the process, specified as an array. The first element in the array is the command/binary to execute, and subsequent array elements are command arguments. The expanded command string is passed directly to exec() without shell or template interpretation. false string(array)  
unlock_root_account If true, the start command is modified to unlock the root user account of the image via usermod, allowing SSH access. false boolean  
user User to run Docker image as. Defaults to user in the Docker image configuration, or 'root' if image doesn't have a user configured. false string  
volume_provider_fqn Volume provider's fully-qualified name. Required if ignore_volumes is not set to true. false string  
volumes A list of volumes used by the Docker image for persistence. false string(array)  

DockerOrigin

For jobs derived from a Docker image, provides information about the origin Docker image. Available in a Job object's docker_origin field.

Name Description Required Schema  
RegistryUrl URL of private Docker registry used to create the job. An empty string indicates the public Docker registry. false string  
ImageName Name of Docker image used to create the job. false string  
ImageTag Tag assigned to the Docker image used to create the job. false string  
Volumes Volumes defined by the Docker image used to create the job. false string array  

Drain

Represents a log drain on a job.

Name Description Required Schema  
url A syslog URL in the form of syslog://hostname:port. false string  
conf Drain configuration object. false DrainConfig  
uuid UUID of the drain object. false string  
max_size Maximum bytes per log line to send. Defaults to 2048 bytes. false integer (int32)  

DrainConfig

Represents the conf property on a log drain.

Name Description Required Schema  
priority The configured syslog priority. false integer (int32)  
protocol The default syslog protocol to dial over. Defaults to TCP. false enum (udp, tcp)  

FileListing

Name Description Required Schema  
name Name of the file or directory in the target path. Directory names are suffixed by a trailing forward slash (for example, /app). false string  
size Size of the file resource; not calculated for directories. false number (float)  

Info

Name Description Required Schema  
name API server name. Currently contains "Continuum". false string  
url URL of Apcera API Server (for example, api.try.apcera.net). false string  
cluster_domain Cluster domain. false string  

Instance

Describes an instance of a job.

Name Description Required Schema  
uuid The instance's unique identifier. false string  
created_time UNIX timestamp for when instance was created. false number (float)  
failed Set to true if the instance has failed in some way. false boolean  
exited Set to true if the instance started and its main process managed to exit. false boolean  
exit_code Exit code of the main processes; should only be checked if exited is true. false integer (int32)  
host Name of the host the instance is running on. false string  
instance_manager UUID of the instance manager running the instance. false string  
state State of the instance. false InstanceState  
job_version_id The sequence number of the job the instance is running. false integer (int64)  
announced_routes Indicates whether the routes for this instance have been announced. false boolean  

InstanceManager

Represents an instance manager.

Name Description Required Schema  
start_time Date and time that instance manager was started. false string  
hostname Instance manager's host name. false string  
uuid Instance manager's unique identifier. false string  
num_instances The number of instances being managed by the instance manager. false integer (int32)  
tags An array of tags assigned to the instance manager. false string array  
system_tags System tags assigned to the instance manager. false string array  
ResourcesTotal Total system resources available to the instance manager. false ResourcesTotal  
ResourcesProvisioned Provisioned system resources available to the instance manager. false ResourcesProvisioned  

InstanceState

Represents a job instance's possible states.

Name Description Required Schema  
NEW Number of instances in the NEW state. false integer (int32)  
SETUP Number of instances in which packages are being installed, networking initialized, etc. false integer (int32)  
STARTING_WAIT Number of instances that are waiting for dependent jobs to become ready. false integer (int32)  
STARTING Number of instances whose processes have been started, but have not been verified to be running. false integer (int32)  
FIRST_RUNNING Number of instances where the job was started and is about to move into the RUNNING state. false integer (int32)  
RUNNING Number of instances that are running. false integer (int32)  
UPDATING Number of instances that are in a state that allows the instance to update various properties of the container. false integer (int32)  
STOPPING_WAIT Number of instances that are being stopped, but have jobs depending on it. In this case the other jobs must first transition past the STOPPING state before this instance can be stopped. false integer (int32)  
STOPPING Number of instances that are in the process of having their processes shutdown. false integer (int32)  
TEARDOWN Number of instances whose user-defined processes have been killed, and the instance is being removed from cluster resources. false integer (int32)  
REMOVED Number of instances that are no longer consuming resources and have no remaining configuration on the system. false integer (int32)  

Job

Represents a job.

Name Description Required Schema  
num_instances The number of job instances currently running. false integer (int32)  
logs Logs this job will be producing that should be collected for aggregation or streaming. false Log  
soft_scheduling_tags List of soft scheduling tags. See Soft Tags for more information. false string  
updated_at Time at which the job was most recently updated. false string (date-time)  
updated_by The principal name of the last user to update the job. false string  
hard_scheduling_tags List of hard scheduling tags. See Hard Tags for more information. false string  
uuid The job's unique identifier (read-only). false string  
created_by The principal name of user who created the job. false string  
created_at Time at which the job was created. false string (date-time)  
state General state of this Job in the system. Possible values are invalid, unknown, created, staging, staging_failed, ready, started, stopped, finished or errored. false string  
health Indicates the health of the job. If empty then the job's health has not been retrieved from the health manager yet. false JobHealth  
resources A list of compute and network resources that this job can consume. false Resource  
tags Map of tags by tag name. false string array  
docker_origin For jobs that run Docker images, specifies the Docker registry, image name and tag that were used to create the job. This field can't be changed after the job is created. false DockerOrigin  
version_id An auto-incremented number that indicates the revision of the object. false integer (int32)  
packages Array of packages for this Job. Includes both user-specified packages and the packages calculated by the package manager. false PackageResource array  
restart The job's restart configuration. false Restart  
processes A map of process names to Process objects. Applications typically define a single process named "app", but the name is not significant. Defining multiple processes is allowed by the API, but is non-deterministic in behavior and not supported. false Process  
fqn Fully Qualified Name. true string  
name Name of the provider. false string  
ports Ports exposed for connectivity on the job. false Port  
labels A map of job labels to their values. true object  
network_ref An object that contains information about the virtual network the job belongs to. false JobNetworkReference  

JobHealth

Represents job health information returned by GET /v1/jobs/health.

Name Description Required Schema  
uuid UUID of the job. false boolean  
score Score is the ratio of running instances to configured instances, capped between 0 and 1. false integer (int32)  
instance_state_count Maps which job instances are in which states, as known by the health manager. false object  

JobNetworkReference

Contains information about the virtual network the job belongs to.

Name Description Required Schema  
uuid UUID of the network the job belongs to. false string  

Log

Represents a job log.

Name Description Required Schema  
file The path to the log file within the job's container that should be collected. false string  
channel The name of the channel that the log should be published on. false string  

ManifestResponse

Represents a successful response to calling either POST /v1/manifests or POST /v1/manifests/expansion.

The response object's location field is only populated in response to calling POST /v1/manifests. The expanded_manifest, expanded_json, and warnings fields are only populated in response to calling POST /v1/manifests/expansion.

Name Description Schema  
location URI of the corresponding Task object that returns the status of a manifest execution. Only populated in responses to POST /v1/manifests. string  
expanded_manifest Contains the expanded manifest from a call to POST /v1/manifests/expansion. string  
expanded_json Contains the expanded manifest in raw JSON format from a call to POST /v1/manifests/expansion. string  
warnings A comma-delimited list of warnings that resulted from a call to POST /v1/manifests/expansion. string  

Package

Represents a package. A package may be an application package, a runtime, or an operating system.

Name Description Required Schema  
created_by The principal name of user who created the package. false string  
created_at Time at which the package was created. false string (date-time)  
dependencies An array of PackageDependency objects. false PackageDependency array  
fqn Package's fully-qualified name. false string  
name Package's local name. false string  
provides An array of PackageProvides objects. false PackageProvides array  
resource An object that describes the package's associated binary resource. Deprecated. Use resources array property instead . false PackageResource  
resources An array of PackageResource objects. false PackageResource array  
staging_pipeline_fqn FQN of the staging pipeline used to stage this package into a runnable state. false String  
stager_job_fqns An array of FQNs of the stager jobs that make up the staging pipeline used to stage the package. false String array  
state Package state (read-only). false string  
updated_at Time at which the package was most recently updated. false string (date-time)  
updated_by The principal name of the last user to update the package. false string  
uuid The package's unique identifier. false string  
version_id Package version. false integer (int32)  

PackageDependency

Describes a dependency that a package has to run.

Name Description Required Schema  
name A string that describes the thing that can be depended upon. Can describe an exact package (e.g. node-4.2.1) or a generalized requirement (e.g. node). false string  
type The type of dependency the package depends on. Can be one of the following: file, package, runtime, or os. false string  

PackageProvides

Describes a requirement that a package can provide to other packages.

Name Description Required Schema  
name A string that describes the thing that can be provided. Can describe an exact package (e.g. node-4.2.1) or a generalized requirement (e.g. node). false string  
type The type of requirement the package provides. Can be one of the following: file, package, runtime, or os. false string  

PackageDependsRequest

Represents a request object for POST /v1/packages/dependencies.

Name Description Required Schema  
job_target Namespace in which dependencies will be resolved (e.g. the namespace of a job that is being staged, the namespace of the user requesting the resolution). false string  
dependencies An array of objects that describe the name and type of dependency to resolve. false DependencyResolve array  

PackageResource

Represents a Package object's binary resource.

Name Description Required Schema  
length The length of the binary resource in bytes. false integer  
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 sha1:, sha256:, sha384:, or sha512:, depending on the hash function used (for example: sha1:3c650b19716f3fe6ca293fbf78795f45ba684ea6). false string  
sha1 Deprecated. Duplicates the digest field for resources encrypted with the SHA-1 algorithm. false string  
uuid The package resource's unique identifier (read-only). false string  

PolicyDocument

Represents a policy document returned by GET /v1/policy/{name}.

Name Description Schema  
description Description of policy extracted from <continuum-policy description=\"Description\"> attribute defined in the policy document. Omitted if document does not contain this attribute. string  
name Name of policy document. string  
updated_at UNIX timestamp for when policy document was last updated. string  
text Text of policy document. string  
version Policy document version. string  

PolicyDocumentInfo

Represents information about a policy document returned by GET /v1/policy.

Name Description Schema  
name Name of policy document. string  
description Description of policy extracted from <continuum-policy description=\"Description\"> attribute defined in the policy document. Omitted if document does not contain this attribute. string  
updated_at UNIX timestamp for when policy documented was last updated. string  
updated_by Principal name of user who last updated the policy document. string  
version Policy document version. string  

PolicyDocumentRequest

The PUT /v1/policy endpoint takes an array of PolicyDocumentRequest objects in the request body. These objects represent policy documents to update or create on the cluster.

To create a new document the PolicyDocumentRequest object need only specify values for its name and text fields. The for_version field must either be omitted, or its value set to 0.

To update an existing policy document, the PolicyDocumentRequest object's name field must match the name of the document to update, and its for_version field must match the current document version. If the versions do not match then the update operation will fail. To obtain a policy document's current version use the GET /v1/policy/{name} endpoint (see Creating and updating policy documents in Apcera REST API Recipes).

Name Description Schema  
name Name of policy document to create or update. string  
for_version For policy document updates, specifies the current version number of the named policy document to update. If the current version does not match for_version then the update is rejected. For new policy document requests, omit this field or set its value to 0. integer  
text Text to insert into policy document. string  

PolicyError

Represents a policy error referenced by an APIError response object's policy_error field. The presence of this field indicates that one or more fields of a job being created or updated violates resource quota policy on that resource. For example, suppose your Apcera cluster has the following policy that limits memory for jobs in /sandbox/admin to 1GB:

on quota::/sandbox/admin{
    {  max.instance.memory 1G  }
}

If you attempt to create or update a job in /sandbox/admin to have greater than 1GiB of memory then a PolicyError is generated. See example below.

Name Description Schema  
errors An array of strings that specify the required changes to the job definition for it to be in compliance with policy. array (string)  
job The Job definition from the original request with necessary modifications to its requested resources for it to be in compliance with policy. integer  
job_changed If true, the job definition in job was adjusted to comply with policy; otherwise false. boolean  
repairable If true the policy error is repairable by making another API request with the modified job object contained in the response object's job field. If false, the same request should not be made again. boolean  

Below is an example APIError that contains a policy_error object. The object's errors field indicates that the job's original memory and disk reservations were adjusted (Memory: 2GiB -> 1GiB, Disk: 3GiB -> 1GiB), and the policy error's job field contains the original Job object with its resources field modified to make the job compliant with quota policy. API clients can use this modified job object in a follow-up API request to create or update the job.

{
  "message": "Job has been adjusted to comply with policy",
  "request_id": "187ee246-6cd4-8574-cf14-062ac668c7fb",
  "missing_claims": null,
  "fatal": false,
  "retry": false,
  "client_side": false,
  "resource_missing": false,
  "duplicate_key": false,
  "request_invalid": false,
  "token_invalid": false,
  "requires_restart": false,
  "client_incompatible": false,
  "code": 499,
  "policy_error": {
    "job_changed": true,
    "job": {
      "uuid": "",
      "updated_by": "",
      "created_by": "admin@apcera.me",
      "updated_at": "0001-01-01T00:00:00Z",
      "created_at": "0001-01-01T00:00:00Z",
      "ports": [
        {
          "number": 222,
          "optional": false
        }
      ],
      "logs": [
        {
          "file": "/logs/stdout.*.log",
          "channel": "job.$JOB_UUID.$INSTANCE_UUID.stdout"
        },
        {
          "file": "/logs/stderr.*.log",
          "channel": "job.$JOB_UUID.$INSTANCE_UUID.stderr"
        }
      ],
      "name": "ubuntu-1404-apc3-1",
      "fqn": "job::/sandbox/admin::ubuntu-1404-apc3-1",
      "num_instances": 1,
      "packages": [
        {
          "uuid": "58e9511e-8cef-4ac9-8a48-5fdfe64e08bc",
          "state": "ready",
          "source": "user"
        }
      ],
      "processes": {
        "init": {
          "start_command_raw": [
            "/sbin/init"
          ],
          "start_command": "",
          "start_command_timeout": 0,
          "stop_command_raw": [],
          "stop_command": "",
          "stop_timeout": 0,
          "heavy": true
        }
      },
      "resources": {
        "cpu": 0,
        "memory": 1073741824,
        "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"
      },
      "state": "started",
      "tags": {
        "heavy": "ubuntu-1404-apc3-1"
      },
      "version_id": 0,
      "network_ref": null,
      "aggregate_network_routes": null
    },
    "repairable": true,
    "errors": [
      "Memory: 2GiB -> 1GiB",
      "Disk: 3GiB -> 1GiB"
    ]
  }
}

PolicySimDocumentInput

Represents a policy document sent in the request body to PUT /v1/sim.

Name Description Schema  
name Name of policy document. string  
text Text to add to the policy document. string  

PolicySimResponse

Represents a response from a request to GET /v1/sim or PUT /v1/sim.

Name Description Schema  
maxl Maximum indentation level for the value column. Integer  
maxv Maximum width of the value column in characters. Integer  
maxc Maximum width of the context field in characters (see Integer  
lines An array of PolicySimResponseLine objects that contain the results of the policy simulation. PolicySimResponseLine  

The maxl, maxv, and maxc fields are provided for display packages (such as APC) that need to know the width of columns when the display format is defined before the data is populated. If the display program decides to indent by 2 characters then (maxl * 2) + maxv is the maximum column width for the value column.

For reference, below is a sample response from GET /v1/sim:

{
  "maxl": 6,
  "maxv": 57,
  "maxc": 29,
  "lines": [
    {
      "level": 0,
      "value": "permit update",
      "context": "(s) clusterPermissions.pol:31",
      "type": 0
    },
    {
      "level": 1,
      "value": "policy::/",
      "context": "(s) clusterPermissions.pol:29",
      "type": 3
    },
    ...
  ]
}

PolicySimResponseLine

Represents a line item in a PolicySimResponse returned by a call to GET /v1/sim or PUT /v1/sim.

Name Description Schema  
context The source of the claim, condition, FQN, or input value, typically the policy file and line number that contains the claim, condition or FQN. For details see Policy Simulation Output Fields. String  
level Indentation level of the line. Useful when displaying simulation responses in a hierarchical view. Also see maxl, maxv, and maxc fields of the PolicySimResponse. Integer  
type An integer that identifies the type of item being described: claim (0), rule (1), input or added input (2), or FQN (3). Integer  
value The value of the claim, rule, input, or FQN being described. string  

Port

Represents a port that is exposed on a job.

Name Description Required Schema  
routes Routes contain the network mappings that connect a URL (over tcp, http) to a given Port. false Route array  
optional Indicates whether or not the instance manager should attempt to verify that connectivity has been established for this Port. false boolean  
number The numerical port exposed for connectivity. false integer (int32)  

Process

Defines the commands used to start and stop a job instance. Each Job object has a processes field that map process names to Process objects. Applications typically define a single process named "app".

Note: Defining multiple processes for job is allowed by the API, but is non-deterministic in behavior and not officially supported.

Name Description Required Schema  
group Name of the Linux group that will be used to run the process. false string  
heavy If true, the process is given 'pid 1' in the new pid namespace within the job's container. This is used to create a capsule. Only one process within the job can set this flag to true. false boolean  
start_command_raw The command used to start the process, specified as an array. The first element in the array is the command/binary to execute, and subsequent array elements are command arguments. The expanded command string is passed directly to exec() without shell or template interpretation. If start_command_raw is provided then start_command, if specified, is ignored. This property is typically used with exact processes that have an extremely well-known start command. false string array  
start_command The command used to start the process within the container's isolation context. false string  
start_command_timeout The number of seconds that the system will wait for startup to complete. This includes the time that it will take for ports to become available. false integer  
stop_command The command used to stop the process within the container's isolation context. If not defined, OS-level signals (like TERM) may be used to shut down the process. false string  
stop_timeout The command used to stop the process, specified as an array. The first element in the array is the command/binary to execute, and subsequent array elements are command arguments. The expanded command string is passed directly to exec() without shell or template interpretation. If stop_command_raw is provided then stop_command, if specified, is ignored. This property is typically used with exact processes that have an extremely well-known start command. false integer  
user Name of a Linux user that will be used to run the process . false string  

Progress

Indicates the progress of a SubTask.

Name Description Schema
current The subtask's current progress. integer
total The total amount of work to be done. integer

Provider

Represents a provider.

Name Description Required Schema  
fqn Provider FQN (Fully Qualified Name). false string  
uuid Provider UUID. false string  
backing_job_fqn Backing job's FQN. false string  
description Provider description. false string  
name Provider name. false string  
type Provider type (e.g. mysql, posgres). false string  
backing_job_port Backing job's port. false string  

Resource

Represents the resources assigned to a job.

Name Description Required Schema  
netmax Maximum amount of network throughput (ceiling) allowed, in bits per second. false integer  
network Amount of network throughput (floor) allocated to the job, in bits per second. false integer  
disk Amount of disk space allocated to the job, in bytes. false integer  
cpu Milliseconds of CPU time per second of physical time allocated to the job. May be greater than 1000ms/second in cases where time is across multiple cores. false integer  
memory Memory allocated to job, in bytes. false integer  

Restart

Represents a job's restart configuration.

Name Description Required Schema  
restart_mode The restart mode to use. Valid values are "always" (default), "no" (never restart), and "failure" (only restart on failure). false string  
maximum_attempts The maximum number of restart attempt to make. false integer (int32)  

Route

Represents a route on a port.

Name Description Required Schema  
auto_provision Read-only property that specifies if the route's endpoint was auto-provisioned by Apcera when it was created (true) or if it was specified explicitly. false boolean  
endpoint Specifies the endopint where the traffic is routed. Valid formats are "http": "hostname" and "tcp": "ip:port". false string  
https_only Specifies if HTTPS should be enforced on the route. By default, clients can access the route using either HTTP or HTTPS. See Enforcing HTTPS on Routes. false boolean  
type Specifies what router should pick up this Route. Valid values are "http" or "tcp". false string  
weight The route's weight (see Sharing Routes and Route Weights). false string  

SemanticPipeline

Represents a semantic pipeline rule.

Name Description Required Schema  
created_by Principal name of user who created the event rule. false string  
created_at UNIX timestamp when event rule was created. false number (float)  
version_id Rule's auto-incremented version number. false integer (int32)  
fqn The rule's fully-qualified name against which policy may be enforced. false string  
provider FQN of the provider to enforce this rule against. In only provider is populated for this rule, then all semantic pipelines consuming a provider matching this FQN will have the rule enforced against them. false string  
service FQN of the service to enforce this rule against. If only service is populated for this rule, then all semantic pipelines consuming a service matching this FQN will have the rule enforced against them. false string  
job FQN of the job to enforce the rule against. false string  
action The type of action to take when the rule is triggered. Can either by 'hook' or 'notification'. false string  
type Type depends upon specified action of event rule, and can specify the timing of the hook firing. false string  

Runtime

Represents the runtimes supported by the built-in staging pipelines.

Name Description Required Schema  
patterns An array of file names or patterns used to select the appropriate runtime. false string array  
runtime Identfies the runtime (for example, "bash", or "perl"). false string  

SemanticPipelineAction

Represents a semantic pipeline rule's actions.

Name Description Required Schema  
commands Array of commands that trigger the hook or notification. false string  
uri URI to invoke for notification. Can only specify one of uri or inline. false string  
inline Action to take. Can only specify one of uri or inline. false string  

Service

Represents a service. Used as input to POST /v1/services requests.

Name Description Schema Required  
uuid Service's unique identifer. string    
fqn Service's fully-qualified name. false string  
provider_fqn Fully-qualified name of provider used to create service. false string  
type Service type (mysql, http, etc.) corresponding to the service gateway to use provision the service. false string  
name Service name. false string  
description Service description. false string  
created_by Principal name of user who created the service. false string  
created_at UNIX timestamp when service was created. false number  
parameters A map of service parameter names to values. false object  

Example service object:

{
  "description":"Network service",
  "fqn":"service::/sandbox/admin::mynet-service",
  "name":"mynet-service",
  "type":"network",
  "parameters": {
    "domainname": "www.apcera.com",
    "portrange": "80",
    "protocol": "tcp"
  }
}

StagerJob

Represents a stager used in a staging pipeline.

Name Description Required Schema  
uuid The UUID of the stager job. false string  

StagingPipeline

Represents a staging pipeline.

Name Description Required Schema  
uuid Staging pipeline's unique identifier. false string  
created_at Date-time when the job was created. false string (date-time)  
created_by User that created the staging pipeline. false string  
fqn Staging pipeline's FQN. false string  
name Staging pipeline's local name. false string  
stagers An array of StagerJob objects. false StagerJob array  
updated_at UNIX timestamp for when the staging pipeline was last updated. false string (date-time)  
updated_by Principal name of the user who last updated the staging pipeline. false string  
version_id Auto-incrementing version ID. false string  

SubnetInfo

Represents information about a virtual network's subnet.

Name Description Required Schema  
Subnet The subnet assigned to a virtual network in CIDR notation (192.168.1.0/24, for example). false string  

SubTask

Represents a discrete piece of work of a TaskEvent stage. For instance, the stage "Creating Package" could contain subtasks of "Checking for Package Existence", "Creating Package", and "Uploading Tarball".

Name Description Schema
name A human-readable description of this subtask. string
index The index of this subtask among all subtasks. Currently not used. string
total The total number of subtasks in the current stage. Currently not used. string
progress Indicates how far along this unit of work is. Currently not used. Progress

Task

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

Name Description Required Schema  
created_at Time when the task was created. false number  
errored Describes the error for a Task that has encountered an error. false string  
events List of all events that have been published for this particular task. false TaskEvent  
state The Task's current state. Can be one of the following values: running (task is still running), stopped (task has stopped) or complete. false string  
time_completed Indicates the time when the task completed. false string  
on_behalf_of Username on whose behalf the auditable action was attempted by principal_name. false integer  
time_started Indicates the time when the task was started. false integer  
updated_at Time at which the task was most recently updated. false integer  
uuid The task's unique identifier. false string  

TaskEvent

Represents an event associated with a Task.

Name Description Required Schema
payload Additional information about the task event. This is typically empty unless an error occurred, in which case it contains a description of the error. false Object
stage A logical grouping of subtasks (for example, "Creating Job" or "Downloading Packages"). false string
subtask A description of the sub-task that this TaskEvent describes. false SubTask
tags A list of tags that provide a hint about what is being tracked. false string(array)
task_event_type The type of message the event contains. Possible values are disconnect, eos (indicates end of event stream), error (indicates an error occurred when running the associated task), event (normal event), or cancel (task was canceled). false string
thread Represents a logically independent procedure within a Task. For instance, a thread could be "job1" or "job2", or "Link job1 and job2". false string
time Time immediately before the TaskEvent was announced on NATS. false string
task_uuid UUID of the Task that stores this event. false string

VirtualNetwork

Represents a virtual network.

Name Description Required Schema  
fqn Network's fully-qualified name. false string  
name Network's local name. false string  
description Network description. false string  
uuid Network's UUID. false string  
subnet_info Object that contains information about the virtual network's subnet. false SubnetInfo  
updated_by Principal name of the last user to update the network. false string  
created_by Principal name of the user who created the network. false string  
updated_at UNIX timestamp when the network was last updated. false Number  
created_at UNIX timestamp when the network was created. false Number  
network_end_points List of network endpoints in the network. false VirtualNetworkEndpoint array  
version_id Auto-incrementing version number. false integer  

VirtualNetworkEndpoint

Represents the connection between a job and a virtual network.

Name Description Required Schema  
uuid The UUID of the network endpoint. false string  
fqn Fully-qualified name of the job the endpoint is attached to. false string  
network_fqn Fully-qualified name of the network that the endpoint belongs to. false string  
end_point_interface A list of virtual network interfaces associated with the job. false VirtualNetworkEndpointInterface array  

VirtualNetworkEndpointInterface

Represents per-instance information for a virtual network endpoint.

Name Description Required Schema  
uuid The UUID of the endpoint interface. false string  
hardware_addr Unique identifier assigned to the network interface. false string  
ipv4_addr Virtual IP address assigned to the instance. false string