REST API for Oracle Cloud Infrastructure Container Service Classic

All REST Endpoints

Authenticate

Use this category of endpoints to authenticate the specified user and then return an authentication token. You can then use that authentication token in subsequent API calls to the Oracle Container Cloud Service.

The process of obtaining a authorization token is as follows:

Use the /auth endpoint to receive a session token.
Use the session token and the /token endpoint to receive a bearer token.
Use the bearer token in the header of any subsequent API calls to the Container service.

Note that the session token has a limited lifetime, but the bearer token does not expire until the /api/token/new endpoint is invoked.

Authenticate with the Service Instance: Method: post
Path: /api/auth
Generate a new authentication token and invalidate the prior token: Method: post
Path: /api/token/new
Get an bearer token to be passed in the header for all API transactions.: Method: post
Path: /api/token

Backup

Use the endpoints in this category to backup and restore the configuration information for an Oracle Container Cloud Service instance. When you use these REST API endpoints, you are using the same features available from the Backup and Restore command on the Container Service console Settings menu.

Export backup server configuration file: Method: get
Path: /api/v2/export
Import a backup server configuration file: Method: post
Path: /api/v2/import

Catalog

To communicate with each other, Docker containers require DNS information to find the location of other containers. Oracle Container Cloud Service maintains DNS information for the running containers that it is managing in its Service Discovery database.

Use the following endpoints to view the entries in the Service Discovery database (also known as the catalog) and to register and deregister items in the database.

Deregister a Service Discovery database item: Method: put
Path: /api/catalog/deregister
Get a list of all items in the Service Discovery database related to a specific service: Method: get
Path: /api/catalog/service/{service_name}
Get a list of all services in the Service Discovery database: Method: get
Path: /api/catalog/services
Register a new Service Discovery database item: Method: put
Path: /api/catalog/register

Container

A Docker container is a process that is created to run an application held in a Docker image.

The Docker container includes everything the application needs in order to run, including executable code, runtime environment, system tools, and system libraries. This approach ensures that the application will always run the same, regardless of the environment in which it is running.

Having deployed a service or stack, you can use the REST API to manage the Docker containers that are created for the deployment. You can also manage Docker containers that are not associated with a deployment because they were started directly from a Docker image.

Get details of a container on a specified host: Method: get
Path: /api/containers/{container_id}/host/{host_id}
Get the logs of a container: Method: get
Path: /api/v2/containers/{container_id}/logs
Kill a container: Method: post
Path: /api/v2/containers/{container_id}/kill
List all containers: Method: get
Path: /api/containers/
List containers currently instantiated by a specific Deployment: Method: get
Path: /api/v2/deployments/{deployment_id}/containers/
Pause a running container: Method: post
Path: /api/v2/containers/{container_id}/pause
Restart a stopped container: Method: post
Path: /api/v2/containers/{container_id}/restart
Start a container: Method: post
Path: /api/v2/containers/{container_id}/start
Stop a running container: Method: post
Path: /api/v2/containers/{container_id}/stop
Unpause a paused container: Method: post
Path: /api/v2/containers/{container_id}/unpause

Deployment

An Oracle Container Cloud Service deployment comprises a service or stack in which Docker containers are managed, deployed, and scaled, according to a set of orchestration rules that you have defined. You can use the REST API to manage your deployments, as well as the webhook assigned to each deployment.

Create a Deployment: Method: post
Path: /api/v2/deployments/
Delete a Deployment: Method: delete
Path: /api/v2/deployments/{deployment_id}
Get a Summary of all Deployments: Method: get
Path: /api/v2/deployments_summary/
Get Deployment details: Method: get
Path: /api/v2/deployments/{deployment_id}
Get the Current Configuration of a Deployment Webhook: Method: get
Path: /api/v2/deployments/{deployment_id}/webhook/restart
Get the Details of a Webhook Assigned to a Deployment: Method: get
Path: /api/v2/deployments/{deployment_id}/webhook
Invoke a Deployment Webhook: Method: post
Path: /api/v2/deployments/{deployment_id}/webhook/restart
List all deployments: Method: get
Path: /api/v2/deployments/
List containers currently instantiated by a specific Deployment: Method: get
Path: /api/v2/deployments/{deployment_id}/containers/
Start a Deployment: Method: post
Path: /api/v2/deployments/{deployment_id}/start
Stop a Deployment: Method: post
Path: /api/v2/deployments/{deployment_id}/stop
Update a Deployment: Method: put
Path: /api/v2/deployments/{deployment_id}
Update the Configuration of a Deployment Webhook: Method: put
Path: /api/v2/deployments/{deployment_id}/webhook/restart

Event

Events are individual, discrete operations. For example, if you deploy a service using the Oracle Container Cloud Service Container Console, five separate events might be initiated:

Add a deployment.
Pull a Docker image from a registry.
Confirm that the docker image has been pulled.
Create a docker image on host.
Start the docker image.

Get list of recent events: Method: get
Path: /api/v2/events/

Host

Hosts are the Oracle Compute virtual machines (VMs) managed by Oracle Container Cloud Service on which you deploy services and stacks to run Docker containers.

You organize the hosts available to you into resource pools to accommodate your workflow, typically grouping together hosts that share a usage or purpose.

Using the REST API, you can monitor the runtime status of a host (active or inactive), the Docker containers running on a host, and the images downloaded to the host. You can also move hosts between resource pools.

Get a detailed list of Docker containers from a specific host: Method: get
Path: /api/hosts/{host_id}/containers/
Get details of a container on a specified host: Method: get
Path: /api/containers/{container_id}/host/{host_id}
Get specific host details: Method: get
Path: /api/hosts/{host_id}
List all hosts: Method: get
Path: /api/hosts/
List all hosts in a resource pool: Method: get
Path: /api/v2/pools/{poolID}/hosts/
Move a host to a new resource pool: Method: put
Path: /api/hosts/{host_id}/pool

Image

A Docker image holds the application that you want Docker to run, along with any dependencies. A Docker image is stored in a Docker registry.

When a service is deployed (either singly, or as part of a stack) for the first time, the Docker image for the service is pulled from the specified Docker registry (either the public Docker registry or a private Docker registry) and added to the list of images managed by Oracle Container Cloud Service.

Use the REST API endpoints in this category to manage the Docker images in your Oracle Container Cloud Service instance.

Delete an Image on a Host: Method: delete
Path: /api/v2/images/{repo_id:.*}/hosts/{host_id}
Get a List of Containers Launched Directly from a Specific Image: Method: get
Path: /api/images/{image_id}/containers/
Get Image Details from a Host: Method: get
Path: /api/images/{image_id}/hosts/{host_id}
List all images: Method: get
Path: /api/images/
Pull an Image to a Specific Host: Method: post
Path: /api/v2/images/{repo_id:.*}/hosts/{host_id}/pull
Push an image from specific host to a a specific registry: Method: post
Path: /api/v2/images/{repo_id:.*}/hosts/{host_id}/push
Run a Container from an Image: Method: post
Path: /api/v2/images/{repo_id:.*}/hosts/{host_id}/run
Tag an image on a specific host: Method: post
Path: /api/v2/images/{image_id}/hosts/{host_id}/tag

Key Value

If you want to hold information in persistent storage, you can save keys and values in the Oracle Container Cloud Service Key/Value Store database for retrieval by calls to the REST API.

You create the keys and store values for keys in the Key/Value Store database using the Oracle Container Cloud Service Container Console. You can then update the value of the keys using the endpoints in this category of the Oracle Container Cloud Service REST API.

For more information, see "Adding Keys and Values to the Key/Value Store Database" in Using Oracle Container Cloud Service.

Add or Update a Key Value entry: Method: put
Path: /api/kv/{key}
Delete a Key Value entry: Method: delete
Path: /api/kv/{key}
Get a Key Value entry: Method: get
Path: /api/kv/{key}

Pool

Resource pools are a way to organize hosts and combine them into isolated pools of compute resources. Resource pools enable you to manage your Docker environment more effectively by deploying services and stacks efficiently across multiple hosts. Oracle Container Cloud Service comes with three resource pools defined out of the box:

Default
Development
Production

The naming of the default resource pools is arbitrary. You can rename these pools, or delete them and create new ones.

Create a new resource pool: Method: post
Path: /api/pools/
Delete a resource pool: Method: delete
Path: /api/pools/{poolID}
Get a detailed list of all resource pools: Method: get
Path: /api/v2/pools/
Get a list of all resource pool configurations: Method: get
Path: /api/pools/
Get resource pool details: Method: get
Path: /api/pools/{poolID}
List all hosts in a resource pool: Method: get
Path: /api/v2/pools/{poolID}/hosts/
Update resource pool: Method: put
Path: /api/pools/{poolID}

Registry

A Docker registry is a system for storing and sharing tagged versions of Docker images. A Docker registry is organized into named repositories. Each Docker repository is associated with a particular version of one or more images.

Create a new registry: Method: post
Path: /api/v2/registries/
Delete a registry: Method: delete
Path: /api/v2/registries/{registry_id}
Get details of a specific registry: Method: get
Path: /api/v2/registries/{registry_id}
List details about available registries: Method: get
Path: /api/v2/registries/
Update a specific registry entry: Method: put
Path: /api/v2/registries/{registry_id}

Use this category of endpoints to search for any occurrence of a string in all values in the API.

Search for a string in all values in the API: Method: post
Path: /api/search/

Service

An Oracle Container Cloud Service service comprises all of the necessary configuration for running a Docker image as a container on a host, plus default deployment directives.

With the REST API, you can list, create, update, and delete services. You can also create a new deployment based on an existing service.

Create a deployment based on a specific Service: Method: post
Path: /api/v2/services/{service_id}/deploy
Create a Service: Method: post
Path: /api/v2/services/
Delete a specific Service: Method: delete
Path: /api/v2/services/{service_id}
Get details on a specific Service: Method: get
Path: /api/v2/services/{service_id}
List all Services: Method: get
Path: /api/v2/services/
Update details on a specific Service: Method: put
Path: /api/v2/services/{service_id}

Stack

An Oracle Container Cloud Service application stack (or simply "stack") comprises all of the necessary configuration for running a set of services as Docker containers in a coordinated way and managed as a single entity, plus default deployment directives.

Create a Stack: Method: post
Path: /api/v2/stacks/
Delete a Stack entry: Method: delete
Path: /api/v2/stacks/{service_id}
Get a list of all Stacks: Method: get
Path: /api/v2/stacks/
Get details on a specific Stack: Method: get
Path: /api/v2/stacks/{service_id}
Update a Stack entry: Method: put
Path: /api/v2/stacks/{service_id}

Status

Status updates report the progress of particular recurring events and tasks. These events include, for example, starting a deployment or running a health check. Status updates have a lifecycle, meaning their severity and description can change.

For example, a container creation event might fail and generate a status update with a severity of Error.

However, if the same container creation event is re-run successfully, the severity of the existing status update is downgraded to Cleared and its description changes. Note that not all events generate status updates.

Get a list of all status updates: Method: get
Path: /api/v2/status/

Tag

Oracle Container Cloud Service tags are a way to categorize and organize resource pools and the hosts within them, enabling you to manage your Docker environment more effectively.

You can use tags for:

Resource pools
Hosts, to collectively identify multiple hosts on which a service can be deployed
Services in the Service Editor, when specifying the hosts on which a service is to run using the per-tag
Deployments, to override the default orchestration details of a service and specify the hosts on which the service is to run

Apply a tag to an object: Method: post
Path: /api/tags/objects/{notused}
Create a tag: Method: post
Path: /api/tags/{notused}
Get an array of all tags: Method: get
Path: /api/tags/
Get an array of tags applied to an object: Method: get
Path: /api/tags/objects/

Task

Tasks are cancelable actions created by Oracle Container Cloud Service in response to your requests. Tasks are long-running, and can involve multiple events and objects. For example, if you stop several containers, Oracle Container Cloud Service creates a task to carry out the action on your behalf because it could take some time for multiple events on each of the containers to complete.

All tasks generate status updates, and can be canceled while they are still running.

Act on a specific Task: Method: post
Path: /api/v2/tasks/{task_id}/{action}
Get details on a specific Task: Method: get
Path: /api/v2/tasks/{task_id}
Get the last 250 tasks: Method: get
Path: /api/v2/tasks/

User

Use the endpoints in this category of the REST API to view and modify the Oracle Container Cloud Service user accounts.

Get the list of users: Method: get
Path: /api/users/
Update the admin user info: Method: put
Path: /api/users/admin

Version

Use the endpoints in this category of the REST API to get information about the version and capabilities of the Oracle Container Cloud Service instance.

Get capabilities of server: Method: get
Path: /api/capabilities
Returns version of server: Method: get
Path: /api/version