490 lines
11 KiB
Markdown
490 lines
11 KiB
Markdown
# 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
|