Sneak peek: Podman's new REST API

This one is just between you and me, don't tell anyone else! Promise? Okay, I have your word, so here goes: There's a brand new REST API that is included with version 2.0 of Podman! That release has just hit testing on the Fedora Project and may have reached stable by the time this post is published. With this new REST API, you can call Podman from platforms such as cURL, Postman, Google's Advanced REST client, and many others. I'm going to describe how to begin using this new API.

The Podman service only runs on Linux. You must do some setup on Linux to get things going.

Install Podman v2.0

First, install Podman v2.0 or later. Currently, you can do that on Fedora with a call such as dnf -y install --enablerepo updates-testing podman, or you can clone Podman from GitHub and then use the Building from scratch instructions near the end of this page.

Set up the REST API

Once Podman v2.0 is installed on your machine, it's time to check out the REST API documentation on docs.podman.io. At the top of this REST document are instructions to set up the REST API service on your Linux server for testing. Here is a look at the command:

# podman system service -t 5000 &

Phew, that was a lot of heavy lifting!

Seriously, it's just that simple. With this command, the service stays up and running for 5000 seconds, and it starts accepting requests. Note that the 5000 seconds uptime is refreshed after every command is received. If you want the service to stay up until the machine goes down or the process is killed, use 0 (zero) instead of 5000. You can do so with this command:

# podman system service -t 0 &

Gather Podman information

Let's take a quick look at a few commands to use against the server now that it's running. First, let's query Podman for its information, and then pipe the results through jq, a command-line JSON processor that's available in most Linux distributions. A quick warning: jq formats the JSON file in a very digestible format, but it can hide errors if they pop up. Let's leverage d in the below curl command to query the Unix domain socket set up when the service was started:

# curl -s --unix-socket /run/podman/podman.sock http://d/v1.0.0/libpod/info | jq
{
 
"host": {
           "arch": "amd64",
           "buildahVersion": "1.15.0",
           "cgroupVersion": "v1",
           "conmon": {
           "package": "Unknown",
           "path": "/usr/local/libexec/podman/conmon",
           "version": "conmon version 2.0.3-dev, commit: 002da2522941fde456f5213c8a5a96c9836c2592"
           },
           "cpus": 1,
           "distribution": {
           "distribution": "fedora",
           "version": "30"
           },
… (removed a number of lines for brevity)
 
"version": {
           "APIVersion": 1,
           "Version": "2.1.0-dev",
           "GoVersion": "go1.13.12",
           "GitCommit": "0e4b73456d4c545136a5cfd664b6d9d819ffc498",
           "BuiltTime": "Sun Jun 21 14:07:25 2020",
           "Built": 1592762845,
           "OsArch": "linux/amd64"
  }
}

This output displays the information about the Podman installation on the Linux server where the REST API service is running.

Next, let's try a couple of small tasks with a little more oomph. Let's pull an image, and then let's list it.

First, we'll pull the Podman image from quay.io. This step could take a few seconds to process. For those new to encoded URL arguments, the %2f below is an escaped forward slash /:

# curl -XPOST --unix-socket /run/podman/podman.sock -v 'http://d/v1.0.0/images/create?fromImage=quay.io%2Fcontainers%2Fpodman'
*  
Trying /run/podman/podman.sock:0...
* Connected to d (/run/podman/podman.sock) port 80 (#0)
> POST /v1.0.0/images/create?fromImage=quay.io%2Fcontainers%2Fpodman HTTP/1.1
> Host: d
> User-Agent: curl/7.65.3
> Accept: */*
> 
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Content-Type: application/json
< Date: Sun, 21 Jun 2020 19:13:19 GMT
< Content-Length: 185
< 
{"status":"pulling image () from quay.io/containers/podman:latest","error":"","progress":"","progressDetail":{},"id":"5a9a0e9623e33dec906d8d38908d0681cee1e09fbdf282fa65fe8dfb878ab943"}
* Connection #0 to host d left intact

Now that we’ve an image pulled down, let’s examine it:

# curl --unix-socket /run/podman/podman.sock -v 'http://d/v1.0.0/libpod/images/json' | jq
*  
Trying /run/podman/podman.sock:0...
  % Total         % Received % Xferd  Average Speed   Time           Time   Time 
Current
                                   Dload 
Upload   Total   Spent Left 
Speed
  0       0         0         0         0         0 
       0         0 --:--:-- --:--:-- --:--:--  0* Connected to d (/run/podman/podman.sock) port 80 (#0)
> GET /v1.0.0/libpod/images/json HTTP/1.1
> Host: d
> User-Agent: curl/7.65.3
> Accept: */*
> 
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Content-Type: application/json
< Date: Sun, 21 Jun 2020 19:16:51 GMT
< Transfer-Encoding: chunked
< 
{ [3980 bytes data]
100  5871       0 
5871           0         0 
38625         0 --:--:-- --:--:-- --:--:-- 39668
* Connection #0 to host d left intact
[
  {
           "Id": "eb7134a03cd6bd8a3de99c16cf174d66ad2d93724bac3307795efcd8aaf914c5",
           "RepoTags": [
           "registry.fedoraproject.org/fedora:32",
           "registry.fedoraproject.org/fedora:latest"
           ],
           "Created": "2020-05-15T06:48:40Z",
           "Size": 207772777,
           "Labels": {
           "license": "MIT",
           "name": "fedora",
           "vendor": "Fedora Project",
           "version": "32"
           },
           "Containers": 1,
           "Names": [
           "registry.fedoraproject.org/fedora:32",
           "registry.fedoraproject.org/fedora:latest"
           ],
… (removed a number of lines for brevity)
           "Names": [
           "quay.io/containers/podman:latest"
           ],
           "Digest": "sha256:1af265e9e85af5d7a4f626c65b136d4eb610b5c7f84873a05e103e91352d6387",
           "Digests": [
           "sha256:1af265e9e85af5d7a4f626c65b136d4eb610b5c7f84873a05e103e91352d6387"
           ],
           "History": [
           "5a9a0e9623e33dec906d8d38908d0681cee1e09fbdf282fa65fe8dfb878ab943",
           "<missing>",
           "<missing>",
           "<missing>",
           "<missing>",
           "eb7134a03cd6bd8a3de99c16cf174d66ad2d93724bac3307795efcd8aaf914c5"
           ]
  }
]

That's it!

It's just that easy to get the REST API service running. You're ready to pull images, create containers, and do any other needed Podman operation. You can also call the service directly through the podman --remote option, or include Podman calls in your Go programs by using the Go bindings. Details on all of that are coming soon.

Wrap up

Granted, in this introduction, I showed only a very small section of the available commands and ways to call the REST API. There's work underway to create a more in-depth blog. In the meantime, the available commands are documented in the Podman API Documentation for your use. The main takeaway today is that if you can do it from Podman's command line, you should be able to do it using this new REST API, too.

Now, remember, this is our little secret!

[ Getting started with containers? Check out this free course. Deploying containerized applications: A technical overview. ]