Struktur Endpoint v1.40 Containers JSON Docker API & Cara Pakai

Kueri /v1.40/containers/json merujuk pada endpoint HTTP REST API resmi Docker Engine versi 1.40 (dirilis pada Docker Engine 19.03) yang berfungsi untuk menampilkan daftar container yang sedang berjalan maupun terhenti—ekuivalen langsung dari perintah CLI docker ps atau docker ps -a.

Endpoint ini diakses via UNIX socket (/var/run/docker.sock) atau TCP socket daemon Docker menggunakan metode GET /v1.40/containers/json. Respons yang dikembalikan berupa JSON array yang berisi metadata lengkap setiap container, mulai dari NetworkSettings, Port mapping, Mounts volume, hingga State eksekusi.

Sintaks Pemanggilan Endpoint & Contoh Respons JSON

Berikut adalah cara memanggil endpoint Docker API v1.40 langsung dari terminal Linux menggunakan cURL via UNIX socket lokal:

# Menampilkan container aktif (ekuivalen 'docker ps')
curl --unix-socket /var/run/docker.sock -X GET "http://localhost/v1.40/containers/json"

# Menampilkan semua container termasuk yang berhenti (ekuivalen 'docker ps -a')
curl --unix-socket /var/run/docker.sock -X GET "http://localhost/v1.40/containers/json?all=true"

Struktur payload JSON standar yang dikembalikan oleh Docker Engine v1.40 adalah array of objects dengan format persis seperti di bawah ini:

[
  {
    "Id": "8dfafdbc3a40bf350291d646faadab92b66fcee45b7cfad4a81d47c33d604e1f",
    "Names": [
      "/web-production"
    ],
    "Image": "nginx:alpine",
    "ImageID": "sha256:51696c87e77e4ff7a53af9be837f35d4eacdb08471230f753d1796e80d4fe1ae",
    "Command": "/docker-entrypoint.sh nginx -g 'daemon off;'",
    "Created": 1711929600,
    "Ports": [
      {
        "IP": "0.0.0.0",
        "PrivatePort": 80,
        "PublicPort": 8080,
        "Type": "tcp"
      }
    ],
    "Labels": {
      "maintainer": "NGINX Docker Maintainers",
      "environment": "production"
    },
    "State": "running",
    "Status": "Up 4 hours",
    "HostConfig": {
      "NetworkMode": "bridge"
    },
    "NetworkSettings": {
      "Networks": {
        "bridge": {
          "IPAMConfig": null,
          "Links": null,
          "Aliases": null,
          "NetworkID": "9b1c90c74780512f4585642a8b321356f7ef57a9f733f114c022880053eb81a7",
          "EndpointID": "d2780e57200be649f3e4bc392945d8b671607f2a74c7e6b0a1a011a4cf135bc3",
          "Gateway": "172.17.0.1",
          "IPAddress": "172.17.0.2",
          "IPPrefixLen": 16,
          "IPv6Gateway": "",
          "GlobalIPv6Address": "",
          "GlobalIPv6PrefixLen": 0,
          "MacAddress": "02:42:ac:11:00:02"
        }
      }
    },
    "Mounts": [
      {
        "Type": "bind",
        "Name": "",
        "Source": "/data/nginx/html",
        "Destination": "/usr/share/nginx/html",
        "Driver": "",
        "Mode": "ro",
        "RW": false,
        "Propagation": "rprivate"
      }
    ]
  }
]

Parameter Query HTTP GET /v1.40/containers/json

Endpoint ini menerima beberapa parameter string query URL untuk memfilter dan membatasi data container yang ditarik aplikasi klien:

Daftar Field JSON dan Fungsinya

Data payload JSON dari endpoint v1.40 memuat atribut vital untuk pemantauan kesehatan container:

Penggunaan Parameter Filter URL Encoded

Parameter filters memerlukan valid JSON string yang kemudian di-URL encode. Sintaks filter Docker v1.40 menggunakan format {"kunci": ["nilai1", "nilai2"]}.

1. Filter Container Berdasarkan Status Exited

Hanya mengambil container yang mati dengan kode error non-zero atau stopped:

# Format JSON filter: {"status": ["exited"]}
curl --unix-socket /var/run/docker.sock -G \
  "http://localhost/v1.40/containers/json" \
  --data-urlencode 'all=true' \
  --data-urlencode 'filters={"status":["exited"]}'

2. Filter Container Berdasarkan Label Environment

Mengambil container yang memiliki label produksi:

# Format JSON filter: {"label": ["environment=production"]}
curl --unix-socket /var/run/docker.sock -G \
  "http://localhost/v1.40/containers/json" \
  --data-urlencode 'filters={"label":["environment=production"]}'

Implementasi Skrip Python Tanpa Library Tambahan (Docker SDK)

Jika ingin membaca endpoint /v1.40/containers/json di sistem backend tanpa menginstal paket berat seperti docker-py, manfaatkan socket standard library Python:

import socket
import json

def get_docker_containers():
    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
    sock.connect('/var/run/docker.sock')
    
    request = (
        "GET /v1.40/containers/json?all=false HTTP/1.1\r\n" 
        "Host: localhost\r\n" 
        "Connection: close\r\n\r\n"
    )
    sock.sendall(request.encode('utf-8'))
    
    response = b""
    while True:
        chunk = sock.recv(4096)
        if not chunk:
            break
        response += chunk
    sock.close()
    
    # Memisahkan HTTP Header dan Body
    header_end = response.find(b"\r\n\r\n")
    body = response[header_end + 4:].decode('utf-8')
    
    # Ekstraksi chunked transfer encoding bila ada
    lines = body.split("\r\n")
    json_data = "".join(lines[1:-1]) if len(lines) > 2 else body
    
    containers = json.loads(json_data)
    return containers

# Eksekusi dan cetak container yang aktif
for c in get_docker_containers():
    print(f"ID: {c['Id'][:12]} | Image: {c['Image']} | Status: {c['Status']}")

Panduan Troubleshooting Lapangan

1. Error: 400 Bad Request (bad parameter)
   Penyebab paling umum adalah format JSON di parameter filters tidak sesuai schema array. Pastikan nilai filter berada di dalam kurung siku ["nilai"], bukan string tunggal "nilai".
2. Error: Permission Denied saat membaca /var/run/docker.sock
   User non-root tidak memiliki akses read/write ke socket Docker default. Solusinya: masukkan user ke grup docker via sudo usermod -aG docker $USER lalu perbarui sesi shell dengan newgrp docker.
3. Performa Lambat pada Daemon Besar
   Hindari menyetel size=true jika host menjalankan ratusan container. Penghitungan disk block layer akan menahan thread daemon Docker dan meningkatkan load CPU server.