Networking API and UX documentation

More doc updates will follow Signed-off-by: Madhu Venugopal <madhu@docker.com>
2026-09-05 13:11:30 +00:00 · 2015-10-07 03:54:27 -07:00
parent 22a9ba090e
commit dd28ded711
21 changed files with 994 additions and 901 deletions
@@ -2484,6 +2484,218 @@ Status Codes
 -   **409** - volume is in use and cannot be removed
 -   **500** - server error

+## 2.5 Networks
+
+### List networks
+
+`GET /networks`
+
+**Example request**:
+
+  GET /networks HTTP/1.1
+
+**Example response**:
+
+  HTTP/1.1 200 OK
+  Content-Type: application/json
+
+```
+  [
+    {
+      "name": "bridge",
+      "id": "f995e41e471c833266786a64df584fbe4dc654ac99f63a4ee7495842aa093fc4",
+      "driver": "bridge"
+    },
+    {
+      "name": "none",
+      "id": "21e34df9b29c74ae45ba312f8e9f83c02433c9a877cfebebcf57be78f69b77c8",
+      "driver": "null"
+    },
+    {
+      "name": "host",
+      "id": "3f43a0873f00310a71cd6a71e2e60c113cf17d1812be2ec22fd519fbac68ec91",
+      "driver": "host"
+    }
+  ]
+```
+
+
+
+Query Parameters:
+
+- **filter** - JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. Available filters: `name=[network-names]` , `id=[network-ids]`
+
+Status Codes:
+
+-   **200** - no error
+-   **500** - server error
+
+### Inspect network
+
+`GET /networks/<network-id>`
+
+**Example request**:
+
+  GET /networks/f995e41e471c833266786a64df584fbe4dc654ac99f63a4ee7495842aa093fc4 HTTP/1.1
+
+**Example response**:
+
+  HTTP/1.1 200 OK
+  Content-Type: application/json
+
+```
+  {
+    "name": "bridge",
+    "id": "f995e41e471c833266786a64df584fbe4dc654ac99f63a4ee7495842aa093fc4",
+    "driver": "bridge",
+    "containers": {
+      "931d29e96e63022a3691f55ca18b28600239acf53878451975f77054b05ba559": {
+        "endpoint": "aa79321e2899e6d72fcd46e6a4ad7f81ab9a19c3b06e384ef4ce51fea35827f9",
+        "mac_address": "02:42:ac:11:00:04",
+        "ipv4_address": "172.17.0.4/16"
+      },
+      "961249b4ae6c764b11eed923e8463c102689111fffd933627b2e7e359c7d0f7c": {
+        "endpoint": "4f62c5aea6b9a70512210be7db976bd4ec2cdba47125e4fe514d18c81b1624b1",
+        "mac_address": "02:42:ac:11:00:02",
+        "ipv4_address": "172.17.0.2/16"
+      },
+      "9f6e0fec4449f42a173ed85be96dc2253b6719edd850d8169bc31bdc45db675c": {
+        "endpoint": "352b512a5bccdfc77d16c2c04d04408e718f879a16f9ce3913a4733139e4f98d",
+        "mac_address": "02:42:ac:11:00:03",
+        "ipv4_address": "172.17.0.3/16"
+      }
+    }
+  }
+```
+
+Status Codes:
+
+-   **200** - no error
+-   **404** - network not found
+
+### Create a network
+
+`POST /networks/create`
+
+Create a network
+
+**Example request**:
+
+  POST /networks/create HTTP/1.1
+  Content-Type: application/json
+
+```
+  {
+    "name":"isolated_nw",
+    "driver":"bridge"
+  }
+```
+
+**Example response**:
+
+  HTTP/1.1 201 Created
+  Content-Type: application/json
+
+```
+  {
+    "id": "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30",
+    "warning": ""
+  }
+```
+
+Status Codes:
+
+- **201** - no error
+- **404** - driver not found
+- **500** - server error
+
+JSON Parameters:
+
+- **name** - The new network's name. this is a mandatory field
+- **driver** - Name of the network driver to use. Defaults to `bridge` driver
+- **options** - Network specific options to be used by the drivers
+- **check_duplicate** - Requests daemon to check for networks with same name
+
+### Connect a container to a network
+
+`POST /networks/(id)/connect`
+
+Connects a container to a network
+
+**Example request**:
+
+  POST /networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/connect HTTP/1.1
+  Content-Type: application/json
+
+```
+  {
+    "container":"3613f73ba0e4"
+  }
+```
+
+**Example response**:
+
+  HTTP/1.1 200 OK
+
+Status Codes:
+
+- **201** - no error
+- **404** - network or container is not found
+
+JSON Parameters:
+
+- **container** - container-id/name to be connected to the network
+
+### Disconnect a container from a network
+
+`POST /networks/(id)/disconnect`
+
+Disconnects a container from a network
+
+**Example request**:
+
+  POST /networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/disconnect HTTP/1.1
+  Content-Type: application/json
+
+```
+  {
+    "container":"3613f73ba0e4"
+  }
+```
+
+**Example response**:
+
+  HTTP/1.1 200 OK
+
+Status Codes:
+
+- **201** - no error
+- **404** - network or container not found
+
+JSON Parameters:
+
+- **container** - container-id/name to be disconnected from a network
+
+### Remove a network
+
+`DELETE /networks/(id)`
+
+Instruct the driver to remove the network (`id`).
+
+**Example request**:
+
+  DELETE /networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30 HTTP/1.1
+
+**Example response**:
+
+  HTTP/1.1 204 No Content
+
+Status Codes
+
+-   **204** - no error
+-   **404** - no such network
+-   **500** - server error
+
 # 3. Going further

 ## 3.1 Inside `docker run`