github.com/slava-ustovytski/docker@v1.8.2-rc1/experimental/networking_api.md (about) 1 # Networking API 2 3 ### List networks 4 5 `GET /networks` 6 7 List networks 8 9 **Example request**: 10 11 GET /networks HTTP/1.1 12 13 **Example response**: 14 15 HTTP/1.1 200 OK 16 Content-Type: application/json 17 18 [ 19 { 20 "name": "none", 21 "id": "8e4e55c6863ef4241c548c1c6fc77289045e9e5d5b5e4875401a675326981898", 22 "type": "null", 23 "endpoints": [] 24 }, 25 { 26 "name": "host", 27 "id": "062b6d9ea7913fde549e2d186ff0402770658f8c4e769958e1b943ff4e675011", 28 "type": "host", 29 "endpoints": [] 30 }, 31 { 32 "name": "bridge", 33 "id": "a87dd9a9d58f030962df1c15fb3fa142fbd9261339de458bc89be1895cef2c70", 34 "type": "bridge", 35 "endpoints": [] 36 } 37 ] 38 39 Query Parameters: 40 41 - **name** – Filter results with the given name 42 - **partial-id** – Filter results using the partial network ID 43 44 Status Codes: 45 46 - **200** – no error 47 - **400** – bad parameter 48 - **500** – server error 49 50 ### Create a Network 51 52 `POST /networks` 53 54 **Example request** 55 56 POST /networks HTTP/1.1 57 Content-Type: application/json 58 59 { 60 "name": "foo", 61 "network_type": "", 62 "options": {} 63 } 64 65 **Example Response** 66 67 HTTP/1.1 200 OK 68 "32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653", 69 70 Status Codes: 71 72 - **200** – no error 73 - **400** – bad request 74 - **500** – server error 75 76 ### Get a network 77 78 `GET /networks/<network_id>` 79 80 Get a network 81 82 **Example request**: 83 84 GET /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653 HTTP/1.1 85 86 **Example response**: 87 88 HTTP/1.1 200 OK 89 Content-Type: application/json 90 91 { 92 "name": "foo", 93 "id": "32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653", 94 "type": "bridge", 95 "endpoints": [] 96 } 97 98 Status Codes: 99 100 - **200** – no error 101 - **404** – not found 102 - **500** – server error 103 104 ### List a networks endpoints 105 106 `GET /networks/<network_id>/endpoints` 107 108 **Example request** 109 110 GET /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653/endpoints HTTP/1.1 111 112 **Example Response** 113 114 HTTP/1.1 200 OK 115 Content-Type: application/json 116 117 [ 118 { 119 "id": "7e0c116b882ee489a8a5345a2638c0129099aa47f4ba114edde34e75c1e4ae0d", 120 "name": "/lonely_pasteur", 121 "network": "foo" 122 } 123 ] 124 125 Query Parameters: 126 127 - **name** – Filter results with the given name 128 - **partial-id** – Filter results using the partial network ID 129 130 Status Codes: 131 132 - **200** – no error 133 - **400** – bad parameter 134 - **500** – server error 135 136 ### Create an endpoint on a network 137 138 `POST /networks/<network_id>/endpoints` 139 140 **Example request** 141 142 POST /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653/endpoints HTTP/1.1 143 Content-Type: application/json 144 145 { 146 "name": "baz", 147 "exposed_ports": [ 148 { 149 "proto": 6, 150 "port": 8080 151 } 152 ], 153 "port_mapping": null 154 } 155 156 **Example Response** 157 158 HTTP/1.1 200 OK 159 Content-Type: application/json 160 161 "b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a" 162 163 Status Codes: 164 165 - **200** – no error 166 - **400** – bad parameter 167 - **500** – server error 168 169 ### Get an endpoint 170 171 `GET /networks/<network_id>/endpoints/<endpoint_id>` 172 173 **Example request** 174 175 GET /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653/endpoints/b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a HTTP/1.1 176 177 **Example Response** 178 179 HTTP/1.1 200 OK 180 Content-Type: application/json 181 182 { 183 "id": "b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a", 184 "name": "baz", 185 "network": "foo" 186 } 187 188 Status Codes: 189 190 - **200** – no error 191 - **404** - not found 192 - **500** – server error 193 194 ### Join an endpoint to a container 195 196 `POST /networks/<network_id>/endpoints/<endpoint_id>/containers` 197 198 **Example request** 199 200 POST /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653//endpoints/b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a/containers HTTP/1.1 201 Content-Type: application/json 202 203 { 204 "container_id": "e76f406417031bd24c17aeb9bb2f5968b628b9fb6067da264b234544754bf857", 205 "host_name": null, 206 "domain_name": null, 207 "hosts_path": null, 208 "resolv_conf_path": null, 209 "dns": null, 210 "extra_hosts": null, 211 "parent_updates": null, 212 "use_default_sandbox": true 213 } 214 215 **Example response** 216 217 HTTP/1.1 200 OK 218 Content-Type: application/json 219 220 "/var/run/docker/netns/e76f40641703" 221 222 223 Status Codes: 224 225 - **200** – no error 226 - **400** – bad parameter 227 - **404** - not found 228 - **500** – server error 229 230 ### Detach an endpoint from a container 231 232 `DELETE /networks/<network_id>/endpoints/<endpoint_id>/containers/<container_id>` 233 234 **Example request** 235 236 DELETE /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653/endpoints/b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a/containers/e76f406417031bd24c17aeb9bb2f5968b628b9fb6067da264b234544754bf857 HTTP/1.1 237 Content-Type: application/json 238 239 **Example response** 240 241 HTTP/1.1 200 OK 242 243 Status Codes: 244 245 - **200** – no error 246 - **400** – bad parameter 247 - **404** - not found 248 - **500** – server error 249 250 251 ### Delete an endpoint 252 253 `DELETE /networks/<network_id>/endpoints/<endpoint_id>` 254 255 **Example request** 256 257 DELETE /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653/endpoints/b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a HTTP/1.1 258 259 **Example Response** 260 261 HTTP/1.1 200 OK 262 263 Status Codes: 264 265 - **200** – no error 266 - **404** - not found 267 - **500** – server error 268 269 ### Delete a network 270 271 `DELETE /networks/<network_id>` 272 273 Delete a network 274 275 **Example request**: 276 277 DELETE /networks/0984d158bd8ae108e4d6bc8fcabedf51da9a174b32cc777026d4a29045654951 HTTP/1.1 278 279 **Example response**: 280 281 HTTP/1.1 200 OK 282 283 Status Codes: 284 285 - **200** – no error 286 - **404** – not found 287 - **500** – server error 288 289 # Services API 290 291 ### Publish a Service 292 293 `POST /services` 294 295 Publish a service 296 297 **Example Request** 298 299 POST /services HTTP/1.1 300 Content-Type: application/json 301 302 { 303 "name": "bar", 304 "network_name": "foo", 305 "exposed_ports": null, 306 "port_mapping": null 307 } 308 309 **Example Response** 310 311 HTTP/1.1 200 OK 312 Content-Type: application/json 313 314 "0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff" 315 316 Status Codes: 317 318 - **200** – no error 319 - **400** – bad parameter 320 - **500** – server error 321 322 ### Get a Service 323 324 `GET /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff` 325 326 Get a service 327 328 **Example Request**: 329 330 GET /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff HTTP/1.1 331 332 **Example Response**: 333 334 HTTP/1.1 200 OK 335 Content-Type: application/json 336 337 { 338 "name": "bar", 339 "id": "0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff", 340 "network": "foo" 341 } 342 343 Status Codes: 344 345 - **200** – no error 346 - **400** – bad parameter 347 - **404** - not found 348 - **500** – server error 349 350 ### Attach a backend to a service 351 352 `POST /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff/backend` 353 354 Attach a backend to a service 355 356 **Example Request**: 357 358 POST /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff/backend HTTP/1.1 359 Content-Type: application/json 360 361 { 362 "container_id": "98c5241f9475e9efc17e7198e931fb48166010b80f96d48df204e251378ca547", 363 "host_name": "", 364 "domain_name": "", 365 "hosts_path": "", 366 "resolv_conf_path": "", 367 "dns": null, 368 "extra_hosts": null, 369 "parent_updates": null, 370 "use_default_sandbox": false 371 } 372 373 **Example Response**: 374 375 HTTP/1.1 200 OK 376 Content-Type: application/json 377 378 "/var/run/docker/netns/98c5241f9475" 379 380 Status Codes: 381 382 - **200** – no error 383 - **400** – bad parameter 384 - **500** – server error 385 386 ### Get Backends for a Service 387 388 Get all backends for a given service 389 390 **Example Request** 391 392 GET /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff/backend HTTP/1.1 393 394 **Example Response** 395 396 HTTP/1.1 200 OK 397 Content-Type: application/json 398 399 [ 400 { 401 "id": "98c5241f9475e9efc17e7198e931fb48166010b80f96d48df204e251378ca547" 402 } 403 ] 404 405 Status Codes: 406 407 - **200** – no error 408 - **400** – bad parameter 409 - **500** – server error 410 411 ### List Services 412 413 `GET /services` 414 415 List services 416 417 **Example request**: 418 419 GET /services HTTP/1.1 420 421 **Example response**: 422 423 HTTP/1.1 200 OK 424 Content-Type: application/json 425 426 [ 427 { 428 "name": "/stupefied_stallman", 429 "id": "c826b26bf736fb4a77db33f83562e59f9a770724e259ab9c3d50d948f8233ae4", 430 "network": "bridge" 431 }, 432 { 433 "name": "bar", 434 "id": "0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff", 435 "network": "foo" 436 } 437 ] 438 439 Query Parameters: 440 441 - **name** – Filter results with the given name 442 - **partial-id** – Filter results using the partial network ID 443 - **network** - Filter results by the given network 444 445 Status Codes: 446 447 - **200** – no error 448 - **400** – bad parameter 449 - **500** – server error 450 451 ### Detach a Backend from a Service 452 453 `DELETE /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff/backend/98c5241f9475e9efc17e7198e931fb48166010b80f96d48df204e251378ca547` 454 455 Detach a backend from a service 456 457 **Example Request** 458 459 DELETE /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff/backend/98c5241f9475e9efc17e7198e931fb48166010b80f96d48df204e251378ca547 HTTP/1.1 460 461 **Example Response** 462 463 HTTP/1.1 200 OK 464 465 Status Codes: 466 467 - **200** – no error 468 - **400** – bad parameter 469 - **500** – server error 470 471 ### Un-Publish a Service 472 473 `DELETE /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff` 474 475 Unpublish a service 476 477 **Example Request** 478 479 DELETE /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff HTTP/1.1 480 481 **Example Response** 482 483 HTTP/1.1 200 OK 484 485 Status Codes: 486 487 - **200** – no error 488 - **400** – bad parameter 489 - **500** – server error