moby--moby/experimental/networking_api.md

Networking API

List networks

GET /networks

List networks

Example request:

    GET /networks HTTP/1.1

Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json

    [
      {
        "name": "none",
        "id": "8e4e55c6863ef4241c548c1c6fc77289045e9e5d5b5e4875401a675326981898",
        "type": "null",
        "endpoints": []
      },
      {
        "name": "host",
        "id": "062b6d9ea7913fde549e2d186ff0402770658f8c4e769958e1b943ff4e675011",
        "type": "host",
        "endpoints": []
      },
      {
        "name": "bridge",
        "id": "a87dd9a9d58f030962df1c15fb3fa142fbd9261339de458bc89be1895cef2c70",
        "type": "bridge",
        "endpoints": []
      }
    ]

Query Parameters:

• name – Filter results with the given name
• partial-id – Filter results using the partial network ID

Status Codes:

• 200 – no error
• 400 – bad parameter
• 500 – server error

Create a Network

POST /networks

Example request

    POST /networks HTTP/1.1
    Content-Type: application/json

    {
      "name": "foo",
      "network_type": "",
      "options": {}
    }

Example Response

    HTTP/1.1 200 OK
    "32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653",

Status Codes:

• 200 – no error
• 400 – bad request
• 500 – server error

Get a network

GET /networks/<network_id>

Get a network

Example request:

    GET /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653 HTTP/1.1

Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json

    {
      "name": "foo",
      "id": "32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653",
      "type": "bridge",
      "endpoints": []
    }

Status Codes:

• 200 – no error
• 404 – not found
• 500 – server error

List a networks endpoints

GET /networks/<network_id>/endpoints

Example request

    GET /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653/endpoints HTTP/1.1

Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json

    [
        {
            "id": "7e0c116b882ee489a8a5345a2638c0129099aa47f4ba114edde34e75c1e4ae0d",
            "name": "/lonely_pasteur",
            "network": "foo"
        }
    ]

Query Parameters:

• name – Filter results with the given name
• partial-id – Filter results using the partial network ID

Status Codes:

• 200 – no error
• 400 – bad parameter
• 500 – server error

Create an endpoint on a network

POST /networks/<network_id>/endpoints

Example request

    POST /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653/endpoints HTTP/1.1
    Content-Type: application/json

    {
      "name": "baz",
      "exposed_ports": [
        {
          "proto": 6,
          "port": 8080
        }
      ],
      "port_mapping": null
    }

Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json

    "b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a"

Status Codes:

• 200 – no error
• 400 – bad parameter
• 500 – server error

Get an endpoint

GET /networks/<network_id>/endpoints/<endpoint_id>

Example request

    GET /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653/endpoints/b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a HTTP/1.1

Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json

    {
        "id": "b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a",
        "name": "baz",
        "network": "foo"
    }

Status Codes:

• 200 – no error
• 404 - not found
• 500 – server error

Join an endpoint to a container

POST /networks/<network_id>/endpoints/<endpoint_id>/containers

Example request

    POST /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653//endpoints/b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a/containers HTTP/1.1
    Content-Type: application/json

    {
        "container_id": "e76f406417031bd24c17aeb9bb2f5968b628b9fb6067da264b234544754bf857",
        "host_name": null,
        "domain_name": null,
        "hosts_path": null,
        "resolv_conf_path": null,
        "dns": null,
        "extra_hosts": null,
        "parent_updates": null,
        "use_default_sandbox": true
    }

Example response

    HTTP/1.1 200 OK
    Content-Type: application/json

    "/var/run/docker/netns/e76f40641703"

Status Codes:

• 200 – no error
• 400 – bad parameter
• 404 - not found
• 500 – server error

Detach an endpoint from a container

DELETE /networks/<network_id>/endpoints/<endpoint_id>/containers/<container_id>

Example request

    DELETE /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653/endpoints/b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a/containers/e76f406417031bd24c17aeb9bb2f5968b628b9fb6067da264b234544754bf857 HTTP/1.1
    Content-Type: application/json

Example response

    HTTP/1.1 200 OK

Status Codes:

• 200 – no error
• 400 – bad parameter
• 404 - not found
• 500 – server error

Delete an endpoint

DELETE /networks/<network_id>/endpoints/<endpoint_id>

Example request

    DELETE /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653/endpoints/b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a HTTP/1.1

Example Response

    HTTP/1.1 200 OK

Status Codes:

• 200 – no error
• 404 - not found
• 500 – server error

Delete a network

DELETE /networks/<network_id>

Delete a network

Example request:

    DELETE /networks/0984d158bd8ae108e4d6bc8fcabedf51da9a174b32cc777026d4a29045654951 HTTP/1.1

Example response:

    HTTP/1.1 200 OK

Status Codes:

• 200 – no error
• 404 – not found
• 500 – server error

Services API

Publish a Service

POST /services

Publish a service

Example Request

    POST /services HTTP/1.1
    Content-Type: application/json

    {
      "name": "bar",
      "network_name": "foo",
      "exposed_ports": null,
      "port_mapping": null
    }

Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json

    "0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff"

Status Codes:

• 200 – no error
• 400 – bad parameter
• 500 – server error

Get a Service

GET /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff

Get a service

Example Request:

    GET /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff HTTP/1.1

Example Response:

    HTTP/1.1 200 OK
    Content-Type: application/json

    {
      "name": "bar",
      "id": "0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff",
      "network": "foo"
    }

Status Codes:

• 200 – no error
• 400 – bad parameter
• 404 - not found
• 500 – server error

Attach a backend to a service

POST /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff/backend

Attach a backend to a service

Example Request:

    POST /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff/backend HTTP/1.1
    Content-Type: application/json

    {
      "container_id": "98c5241f9475e9efc17e7198e931fb48166010b80f96d48df204e251378ca547",
      "host_name": "",
      "domain_name": "",
      "hosts_path": "",
      "resolv_conf_path": "",
      "dns": null,
      "extra_hosts": null,
      "parent_updates": null,
      "use_default_sandbox": false
    }

Example Response:

    HTTP/1.1 200 OK
    Content-Type: application/json

    "/var/run/docker/netns/98c5241f9475"

Status Codes:

• 200 – no error
• 400 – bad parameter
• 500 – server error

### Get Backends for a Service

Get all backends for a given service

Example Request

    GET /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff/backend HTTP/1.1

Example Response

    HTTP/1.1 200 OK
    Content-Type: application/json

    [
      {
        "id": "98c5241f9475e9efc17e7198e931fb48166010b80f96d48df204e251378ca547"
      }
    ]

Status Codes:

• 200 – no error
• 400 – bad parameter
• 500 – server error

List Services

GET /services

List services

Example request:

    GET /services HTTP/1.1

Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json

    [
      {
        "name": "/stupefied_stallman",
        "id": "c826b26bf736fb4a77db33f83562e59f9a770724e259ab9c3d50d948f8233ae4",
        "network": "bridge"
      },
      {
        "name": "bar",
        "id": "0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff",
        "network": "foo"
      }
    ]

Query Parameters:

• name – Filter results with the given name
• partial-id – Filter results using the partial network ID
• network - Filter results by the given network

Status Codes:

• 200 – no error
• 400 – bad parameter
• 500 – server error

Detach a Backend from a Service

DELETE /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff/backend/98c5241f9475e9efc17e7198e931fb48166010b80f96d48df204e251378ca547

Detach a backend from a service

Example Request

    DELETE /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff/backend/98c5241f9475e9efc17e7198e931fb48166010b80f96d48df204e251378ca547 HTTP/1.1

Example Response

    HTTP/1.1 200 OK

Status Codes:

• 200 – no error
• 400 – bad parameter
• 500 – server error

### Un-Publish a Service

DELETE /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff

Unpublish a service

Example Request

    DELETE /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff HTTP/1.1

Example Response

    HTTP/1.1 200 OK

Status Codes:

• 200 – no error
• 400 – bad parameter
• 500 – server error