Bluemix

IBM Containers API

Containers are virtual software objects that include all the elements that an app needs to run. A container has the benefits of resource isolation and…

Developer tools#openapi#developer-tools

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

Containers are virtual software objects that include all the elements that an app needs to run. A container has the benefits of resource isolation and allocation but is more portable and efficient than, for example, a virtual machine.

This documentation describes the IBM Containers API, which is based on the Docker Remote API. The API provides endpoints that you can use to create and manage your single containers and container groups in Bluemix. Endpoints are summarized under the following tags:

  • Authentication: Retrieve and refresh your TLS certificates.
  • Private Docker images registry: Create your own private Docker images registry in Bluemix by setting a namespace for your organization.
  • Images: View, build, and push your images to your private Bluemix registry so you can use them with IBM Containers. You can also scan your container images with the Vulnerability Advisor against standard policies set by the organization manager and a database of known Ubuntu issues.
  • Single Containers: Create and manage single containers in Bluemix. Use a single container to implement short-lived processes or to run simple tests as you develop an app or service. To make your single container available from the internet, review the Public IP addresses endpoints.
  • Container Groups: Create and manage your container groups in Bluemix. A container group consists of multiple single containers that are all created from the same container image and as a consequence are configured in the same way. Container groups offer further options at no cost to make your app highly available. These options include in-built load balancing, auto-recovery of unhealthy container instances, and auto-scaling of container instances based on CPU and memory usage. Map a public route to your container group to make your app accessible from the internet.
  • Public IP addresses: Use these endpoints to request public IP addresses for your space. You can bind this IP address to your container to make your container accessible from the internet.
  • File shares: Create, list and delete file shares in a space. A file share is a NFS storage system that hosts Docker volumes.
  • Volumes: Create and manage container volumes in your space to persist the data of your containers.

Each API request requires an HTTP header that includes the 'X-Auth-Token’ and 'X-Auth-Project-Id’ parameter.

  • X-Auth-Token: The JSON web token (JWT) that you receive when logging into the Bluemix platform. It allows you to use the IBM Containers REST API, access services, and resources. Run cf oauth-token to retrieve your access token information.
  • X-Auth-Project-Id: The unique ID of your organization space where you want to create or work with your containers. Run cf space --guid, where is the name of your space, to retrieve your space ID.

For further information about how containers work in the IBM Containers service, review the documentation under https://new-console.ng.bluemix.net/docs/containers/container_index.html.

Endpoints 47

Images

  • POSTBuild a Docker image from a Dockerfile/build?t=string&q=true&nocache=true&pull=trueThis API builds a new container image from a Dockerfile that is stored on your local machine and pushes the image to the private Bluemix registry…
  • GETList all Docker images that are available in your private Bluemix registry./images/jsonThis endpoint returns a list of all available Docker images in a private Bluemix registry (corresponding IBM Containers command: cf ic images.
  • DELETERemove a Docker image./images/:idRemove a Docker image from the private Bluemix registry that is identified by the image ID (corresponding IBM Containers command: cf ic rmi <image>).
  • GETInspect a Docker image in private Bluemix registry/images/:name_or_id/jsonThis endpoint returns detailed information about a Docker image that is stored in the private Bluemix registry of an organization (corresponding IBM…

Single containers

  • POSTCreate and start a single container/containers/create?name=stringThis endpoint creates and starts a single container in your space based on the Docker image that is specified in the Image field of the request json. A single…
  • GETList single containers in a space./containers/json?all=string&filters=stringThis endpoint returns a list of all single containers in a space that are currently in a running state (corresponding IBM Containers command: cf ic ps). To…
  • GETList the current state of a container./containers/:id/statusThis endpoint returns the current state of a container. This state can either be a transient state, such as BUILDING and NETWORKING, or a non-transient state,…
  • DELETERemove a single container/containers/:name_or_id?force=trueRemove a single container that is identified by container ID or name from a space (corresponding IBM Containers command: cf ic delete <container>). The…
  • GETInspect a single container/containers/:name_or_id/jsonThis endpoint retrieves detailed information about a single container (corresponding IBM Containers command: cf ic inspect <container>).
  • POSTPause a single container/containers/:name_or_id/pausePause all processes in a running single container with a given container ID or name (corresponding IBM Containers command: cf ic pause <container>).
  • POSTRename a single container/containers/:name_or_id/rename?name=stringChange the current name of an existing single container that is identified by the container ID or name (corresponding IBM Containers command: cf ic rename…
  • POSTRestart a single container/containers/:name_or_id/restart?t=0Restart a container with a given container ID or name (corresponding IBM Containers command: cf ic restart <container>).
  • POSTStart a single container/containers/:name_or_id/startStart a single container with a given container name or ID (corresponding IBM Containers command: cf ic start <container>).
  • POSTStop a single container/containers/:name_or_id/stop?t=0Stop a single container with a given container name or ID (corresponding IBM Containers command: cf ic stop <container>).
  • POSTUnpause a single container/containers/:name_or_id/unpauseUnpause all processes that are currently stopped inside a single containers with a given container ID or name (corresponding IBM Containers command: cf ic…

Public IP addresses

  • GETList available public IP addresses in a space/containers/floating-ips?all=trueThis endpoint returns a list of all public IP addresses that are allocated to a space and not bound to a container. If you want to list all public IP…
  • POSTRequest a public IP address for a space/containers/floating-ips/requestThis endpoint requests a new public IP address for a space (corresponding IBM Containers command: cf ic ip request). The number of public IP addresses depends…
  • POSTRelease public IP address/containers/floating-ips/:ip/releaseThis endpoint releases a public IP address from a space (corresponding IBM Containers command: cf ic ip release <ip_adress>). The public IP address is no…
  • POSTBind a public IP address to a single container/containers/:name_or_id/floating-ips/:ip/bindThis endpoint binds an available public IP address to a single container (corresponding IBM Containers command: cf ic ip bind <ip_adress> <container>). After…
  • POSTUnbind a public IP address from a container/containers/:name_or_id/floating-ips/:ip/unbindThis endpoint unbinds a public IP address from a container (corresponding IBM Containers command: cf ic ip unbind <ip_adress> <container>). The container that…

Container Groups

  • GETList all container groups in a space/containers/groupsThis endpoint returns a list of all container groups in a space independent of their current state. (corresponding IBM Containers command: cf ic group list).
  • POSTCreate and start a container group./containers/groupsThis endpoint creates and starts a new container group in your space. A container group consists of two or more single containers that are all created from…
  • GETInspect a container group./containers/groups/:name_or_idThis endpoint retrieves detailed information about a container group with a given name (corresponding IBM Containers command: cf ic group inspect GROUP).
  • DELETEStop and delete all container instances in a container group./containers/groups/:name_or_id?force=stringStops and deletes the container instances that run in a container group (corresponding IBM Containers command: cf ic group rm <group_name>). When you delete a…
  • PATCHUpdate a container group./containers/groups/:name_or_idUpdate the number of container instances that run in a container group (corresponding IBM Containers command: cf ic group update <option> <group>). Note: You…
  • POSTMap a public route to a container group./containers/groups/:name_or_id/maprouteIf you want your container group to be accessible from the Internet, you need to expose a public port and map a public route to it (corresponding IBM…
  • POSTUnmap a public route from a container group/containers/groups/:name_or_id/unmaprouteThis endpoint unmaps a public route from a container group (corresponding IBM Containers command: cf ic route unmap -n <host> -d <domain> <group>). If no…

API info

  • GETList messages for the user/containers/messagesThis endpoint retrieves all IBM Containers system messages for the user.
  • GETList latest API version/containers/versionThis endpoint retrieves a list of all microservices that are used in the IBM Containers service with their current build version. This method does not require…

Quota

  • GETRetrieve organization and space specific quota/containers/quotaRetrieve the quota that is assigned to the organization and space.
  • PUTUpdate space quota/containers/quotaThis endpoint updates the quota that is allocated to a Bluemix space. Note: Only paid accounts are eligbile to update the space quota. If you are using a…
  • GETList container sizes and quota limits/containers/usageThis endpoint returns a list of available container sizes and the quota limit and usage for the space. Container sizes: A list of available container sizes…

Private Docker images registry

  • GETRetrieve the namespace of an organization./registry/namespacesThis endpoint retrieves the namespace that was set for the organization that owns the current space (corresponding IBM Containers command: cf ic namespace get).
  • GETCheck the availability of a namespace/registry/namespaces/:namespaceThis endpoint checks whether a namespace is available in Bluemix and can be used to set up the private Docker images registry for an organization. When a HTTP…
  • PUTSet a namespace for your private Bluemix registry./registry/namespaces/:namespaceSet up your own Docker images registry in Bluemix by defining a namespace for your organization (corresponding IBM Containers command: cf ic namespace set…

Authentication

  • GETRetrieve the TLS Certificate/tlskeyThis endpoint returns the TLS (Transport Layer Security) certificate to the user (corresponding IBM Containers command: cf ic login). The TLS certificate is a…
  • PUTRefresh the TLS Certificate/tlskey/refreshThis endpoint requests to generate a new TLS (Transport Layer Security) certificate on the server and to update the existing user TLS certificate…

Volumes

  • POSTCreate a volume in a space/volumes/create?name=string&fsName=stringThis endpoints creates a new volume in your space (corresponding IBM Containers command: cf ic volume create VOLNAME). A volume is used to persist and access…
  • GETList all volumes for a space/volumes/jsonThis endpoint returns a list of all volumes that are available in the given space (corresponding IBM Containers command: cf ic volume list).
  • POSTShare a volume with another space/volumes/:nameThis endpoint provisions an existing volume that was created in one space to another space within the same organization. Single containers and container…
  • DELETEDelete a volume/volumes/:nameDelete a volume with a given name from a space (corresponding IBM Containers command: cf ic volume rm VOLNAME). To delete a volume, all mounted containers…
  • GETRetrieve detailed information about a volume. /volumes/:name/jsonRetrieve a detailed list of information about a volume that is identified by the volume name (corresponding IBM Containers command: cf ic volume inspect…

File shares

  • POSTCreate a file share in a space/volumes/fs/createThis endpoint creates a new file share in a space (corresponding IBM Containers command: cf ic volume fs-create FSNAME FSSIZE FSIOPS). A file share is a…
  • GETList available file share sizes/volumes/fs/flavors/jsonThis endpoint returns a list of available file shares in gigabyte (corresponding IBM Containers command: cf ic volume fs-flavor-list).
  • GETList available file shares in a space/volumes/fs/jsonThis endpoint returns a list of all file shares that are availble in a space (corresponding IBM Containers command: cf ic volume fs-list).
  • DELETEDelete a file share/volumes/fs/:nameThis endpoint deletes a file share from a space (corresponding IBM Containers command: cf ic volume fs-rm FSNAME). Before you can delete a file share, all…
  • GETInspect a file share/volumes/fs/:name/jsonThis endpoint returns detailed information about a file share (corresponding IBM Containers command: cf ic volume fs-inspect FSNAME).

API details

Base URL
https://containers-api.ng.bluemix.net/v3
Authentication
None declared in the description
Operations
47 operations on 41 pathsGET 20POST 18DELETE 5PUT 3PATCH 1
Main resources
Single containers 11Container Groups 7File shares 5Public IP addresses 5Volumes 5Images 4Private Docker images registry 3Quota 3API info 2Authentication 2
Response formats
application/json
Description format
OpenAPI 3.0.0, API version 3.0.0
Listed from
APIs.guru OpenAPI Directory (CC0-1.0)
Source updated

How to test the IBM Containers API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the IBM Containers API collection, without the publisher's secrets.
  3. Add your credentialsOpen the collection's variables or an environment and enter your API key or token, if the API needs one.
  4. Send a requestPick an endpoint, for example “Build a Docker image from a Dockerfile” (POST /build?t=string&q=true&nocache=true&pull=true), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the IBM Containers API?

Containers are virtual software objects that include all the elements that an app needs to run. A container has the benefits of resource isolation and… It is listed under Developer tools and has 47 endpoints.

Who publishes the IBM Containers API?

It is listed from Bluemix's public API description (an OpenAPI document), not published by Bluemix on Swastik Codes. Anyone who controls bluemix.net can claim the profile by adding a DNS TXT record.

What is the base URL of the IBM Containers API?

Requests go to https://containers-api.ng.bluemix.net/v3. Endpoint paths are added to this base URL.

How do I authenticate with the IBM Containers API?

Its OpenAPI description does not declare an authentication scheme. Some endpoints may be open; check the provider's documentation before relying on that.

How many endpoints does the IBM Containers API have?

47 operations on 41 paths (20 GET, 18 POST, 5 DELETE, 3 PUT, 1 PATCH). The largest groups are Single containers, Container Groups, File shares, Public IP addresses.

Is forking the IBM Containers API free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.