Introduction

Welcome to the Shipyard API docs! Everything in Shipyard is controlled through the API. These docs will explain how to use the Shipyard API for custom integrations.

programming-593312_1280

Docker

In addition to the Shipyard API, Shipyard also provides full compatibility for the Docker Remote API. You can use the Docker Remote API for container operations such as create, start, stop and more. Shipyard will pass any request to the Docker Remote API to Swarm. See the Docker Remote API Documentation for full reference.

Authentication

To access the Shipyard API, you must be authenticated. The recommended way is to use service keys however, you can also use authorization tokens. To create a Service Key. All requests must have a header including either the service key or authorization token.

Login

HTTP Request

POST /auth/login

This will return an authorization token. This is not the same as a service key. Authorization tokens are used for user login.

POST /auth/login HTTP/1.1
Content-Type: application/json

{
  "username": "admin",
  "password": "password"
}

Response

{
  "auth_token": "$2a$10$QKbbcXM5pUUXM/0bTwC8re/PU2jB5wqLEyUcRZtHcavjwdfmW/y4W",
  "user_agent":"curl/7.35.0"

}

Requests

For requests, you must include either an authorization token or service key with the request as a header.

Auth MethodHeaderExample
Service KeyX-Service-KeyX-Service-Key:12345
Auth TokenX-Access-TokenX-Access-Token:admin:$2$34...xxx

For the examples below, make sure to replace “username” and “token” with your own username and token.

GET /1.17/version HTTP/1.1
Content-Type: application/json
X-Access-Token: username:token

Response Output

{
  "Version": "swarm/0.4.0",
  "APIVersion": "1.17",
  "GoVersion": "go1.4.2",
  "GitCommit": "HEAD",
  "Os": "linux",
  "Arch": "amd64"
}

Accounts

Shipyard provides authentication and access control. The accounts API enables management around the creation and modification of the accounts.

List Accounts

HTTP Request

GET /api/accounts

This will list all accounts in Shipyard along with their roles.

FieldTypeDescription
first_namestringUser first name
last_namestringUser last name
usernamestringUsername
passwordstringEncrypted password
roleslist of stringsRoles assigned to user
GET /api/accounts HTTP/1.1
Content-Type: application/json
X-Access-Token: username:token

Response

[
    {
        "id": "d4a1e6ae-f90d-46bd-abcd-08f9ce1a5bb2",
        "first_name": "Shipyard",
        "last_name": "Admin",
        "username": "admin",
        "password": "$2a$10$fhEE05Gk3t8HIafjJfmChuq53drUlyCHyRv7QtJZ6Rl8szHS54432",
        "roles": [
          "admin"
        ]
    }
]

Create an Account

HTTP Request

POST /api/accounts

This will create a new Shipyard account. The user data is expected to be posted as JSON content.

FieldTypeDescription
usernamestringusername
passwordstringpassword
roleRoleRole to assign to user
POST /api/accounts HTTP/1.1
Content-Type: application/json
X-Access-Token: username:token

{
  "username": "foo",
  "password": "bar",
  "role": {
    "name": "user"
  }
}

Response

HTTP/1.1 204 No Content

Delete an Account

HTTP Request

DELETE /api/accounts

This will delete an account. The username is expected to be posted as JSON content.

FieldTypeDescription
usernamestringusername
DELETE /api/accounts HTTP/1.1
Content-Type: application/json
X-Access-Token: username:token

{
  "username": "foo"
}

Response

HTTP/1.1 204 No Content

Roles

The Roles API provides management for account roles.

List Roles

HTTP Request

GET /api/roles

This will list the roles and access privileges.

FieldTypeDescription
role_namestringName of Role
descriptionstringDescription of role
ruleslist of rule objectsList of rule objects describing the path and allowed methods
GET /api/roles HTTP/1.1
Content-Type: application/json
X-Access-Token: username:token

Response

[
  {
    "role_name": "admin",
    "description": "Administrator",
    "rules": [
      {
        "path": "*",
        "methods": [
          "*"
        ]
      }
    ]
  },
  {
    "role_name": "containers:ro",
    "description": "Containers Read Only",
    "rules": [
      {
        "path": "/containers",
        "methods": [
          "GET"
        ]
      }
    ]
  }
]

Get a Role

HTTP Request

GET /api/roles/(name)

FieldDescription
nameName of the Role
GET /api/roles/admin HTTP/1.1
Content-Type: application/json
X-Access-Token: username:token

Response

{
    "role_name": "admin",
    "description": "Administrator",
    "rules": [
        {
            "path": "*",
            "methods": [
                "*"
            ]
        }
    ]
}

Create a Role

HTTP Request

POST /api/roles

This will create a new Role. The user data is expected to be posted as JSON content.

FieldTypeDescription
namestringName of Role
POST /api/roles HTTP/1.1
Content-Type: application/json
X-Access-Token: username:token

{
  "name": "test"
}

Response

HTTP/1.1 204 No Content

Delete a Role

HTTP Request

DELETE /api/roles

This will delete a role. The username is expected to be posted as JSON content.

FieldTypeDescription
usernamestringusername
DELETE /api/roles HTTP/1.1
Content-Type: application/json
X-Access-Token: username:token

{
  "name": "test"
}

Response

HTTP/1.1 204 No Content

Nodes

This returns information on the Swarm nodes in the cluster.

List Nodes

HTTP Request

GET /api/nodes

GET /api/nodes HTTP/1.1
Content-Type: application/json
X-Access-Token: username:token

Response

[
    {
        "name": "node-00",
        "addr": "10.0.1.1:2376",
        "containers": "10",
        "reserved_cpus": "0 / 10",
        "reserved_memory": "0 B / 4.84 GiB",
        "labels": [
            "executiondriver=native-0.2",
            " kernelversion=3.16.0-4-amd64",
            " operatingsystem=Debian GNU/Linux 8 (jessie)",
            " storagedriver=aufs"
        ],
        "response_time": 0
    },
    {
        "name": "node-01",
        "addr": "10.0.1.2:2376",
        "containers": "10",
        "reserved_cpus": "0 / 10",
        "reserved_memory": "0 B / 4.84 GiB",
        "labels": [
            "executiondriver=native-0.2",
            " kernelversion=3.16.0-4-amd64",
            " operatingsystem=Debian GNU/Linux 8 (jessie)",
            " storagedriver=aufs"
        ],
        "response_time": 0
    }
]

Get a Node

HTTP Request

GET /api/nodes/(name)

NameDescription
nameName of the node to get
GET /api/nodes/node-00 HTTP/1.1
Content-Type: application/json
X-Access-Token: username:token

Response

{
    "name": "node-00",
    "addr": "10.0.1.1:2376",
    "containers": "10",
    "reserved_cpus": "0 / 10",
    "reserved_memory": "0 B / 4.84 GiB",
    "labels": [
        "executiondriver=native-0.2",
        " kernelversion=3.16.0-4-amd64",
        " operatingsystem=Debian GNU/Linux 8 (jessie)",
        " storagedriver=aufs"
    ],
    "response_time": 0
}

Registries

This provides management for Docker Registries attached to the cluster.

List Registries

HTTP Request

GET /api/registries

GET /api/registries HTTP/1.1
Content-Type: application/json
X-Access-Token: username:token

Response

[
    {
        "id": "7b4d261c-5ac4-481a-b1fa-1808355becf8",
        "name": "local",
        "addr": "http://127.0.0.1:5000"
    }
]

Get a Registry

HTTP Request

GET /api/registries/(name)

Parameters

NameDescription
nameName of the Registry
GET /api/registries/local HTTP/1.1
X-Access-Token: username:token

Response

{
    "id": "7b4d261c-5ac4-481a-b1fa-1808355becf8",
    "name": "local",
    "addr": "http://127.0.0.1:5000"
}

List Repositories

HTTP Request

GET /api/registries/(name)/repositories

Parameters

NameDescription
nameName of the Registry
GET /api/registries/local/repositories HTTP/1.1
X-Access-Token: username:token

Response

[
    {
        "name": "library/registry",
        "namespace": "library",
        "repository": "registry",
        "tags": [
            {
              "ID": "8c2e06607696bd4afb3d03b687e361cc43cf8ec1a4a725bc96e39f05ba97dd55",
              "Name": "latest"
            }
        ],
        "layers": [],
        "size": 2433303
    }
]

Get a Repository

HTTP Request

GET /api/registries/(name)/repositories/(repository)

Parameters

NameDescription
nameName of the Registry
repositoryName of the Repository
GET /api/registries/local/repositories/library/registry HTTP/1.1
X-Access-Token: username:token

Response

{
    "name": "library/registry",
    "namespace": "library",
    "repository": "registry",
    "tags": [
        {
          "ID": "8c2e06607696bd4afb3d03b687e361cc43cf8ec1a4a725bc96e39f05ba97dd55",
          "Name": "latest"
        }
    ],
    "layers": [],
    "size": 2433303
}

Delete a Repository

HTTP Request

DELETE /api/registries/(name)/repositories/(repository)

NameDescription
nameName of the Registry
repositoryName of the Repository
DELETE /api/registries/local/repositories/library/busybox HTTP/1.1
X-Access-Token: username:token

Response

HTTP/1.1 204 No Content

Service Keys

This provides management for Service Keys.

List Service Keys

HTTP Request

GET /api/servicekeys

FieldTypeDescription
keystringService Key
descriptionstringDescription of key
GET /api/servicekeys HTTP/1.1
Content-Type: application/json
X-Access-Token: username:token

Response

[
    {
        "key": "jyGFOFLPhG3qE2WrgSuEJe/7zJLpiIaLuyA6",
        "description": "test key"
    }
]

Create a Service Key

HTTP Request

POST /api/servicekeys

FieldTypeDescription
descriptionstringDescription of the service key
POST /api/servicekeys HTTP/1.1
Content-Type: application/json
X-Access-Token: username:token

{
    "description": "test key"
}

Response

{
    "key": "jyGFOFLPhG3qE2WrgSuEJe/7zJLpiIaLuyA6",
    "description": "test key"
}

Delete a Service Key

HTTP Request

DELETE /api/servicekeys

FieldTypeDescription
keystringService Key
DELETE /api/servicekeys HTTP/1.1
Content-Type: application/json
X-Access-Token: username:token

{
    "key": "jyGFOFLPhG3qE2WrgSuEJe/7zJLpiIaLuyA6"
}

Response

HTTP/1.1 204 No Content

Webhook Keys

This provides management for Webhook Keys. Webhook keys are used for deployment using the Docker Hub.

List Webhook Keys

HTTP Request

GET /api/webhookkeys

FieldTypeDescription
idstringInternal ID of key
keystringService Key
descriptionstringDescription of key
GET /api/webhookkeys HTTP/1.1
Content-Type: application/json
X-Access-Token: username:token

Response

[
    {
        "id": "cb20156f-0688-4e3c-94a6-a8cc9966d20f",
        "image": "ehazlett/docker-demo",
        "key": "9953f2f31ad8bc05"
    }
]

Create a Webhook Key

HTTP Request

POST /api/webhookkeys

FieldTypeDescription
imagestringName of the Docker Image to use in the key
POST /api/webhookkeys HTTP/1.1
Content-Type: application/json
X-Access-Token: username:token

{
    "image": "ehazlett/docker-demo"
}

Response

{
    "image": "ehazlett/docker-demo",
    "key": "9953f2f31ad8bc05"
}

Delete a Webhook Key

HTTP Request

DELETE /api/webhookkeys/(key)

Parameters

NameDescription
keyWebhook key
DELETE /api/servicekeys/9953f2f31ad8bc05 HTTP/1.1
Content-Type: application/json
X-Access-Token: username:token

Response

HTTP/1.1 204 No Content

Deploy using Webhook

HTTP Request

POST /hub/webhook/(key)

Data is expected to be in the format of the Docker Hub build payload.

You can also trigger a deploy manually by sending a payload as follows:


{
"repository": {
"repo_name": "ehazlett/docker-demo"
}
}

POST /hub/webhook/9953f2f31ad8bc05 HTTP/1.1
Content-Type: application/json

{
    "push_data":{
        "pushed_at":1385141110,
        "images":[
            "imagehash1",
            "imagehash2",
            "imagehash3"
        ],
        "pusher":"username"
    },
    "repository":{
        "status":"Active",
        "description":"my docker repo that does cool things",
        "is_trusted":false,
        "full_description":"This is my full description",
        "repo_url":"https://registry.hub.docker.com/u/username/reponame/",
        "owner":"username",
        "is_official":false,
        "is_private":false,
        "name":"reponame",
        "namespace":"username",
        "star_count":1,
        "comment_count":1,
        "date_created":1370174400,
        "dockerfile":"my full dockerfile is listed here",
        "repo_name":"username/reponame"
    }
}

Response

HTTP/1.1 200 OK

Events

Events provide auditing and information for all actions in Shipyard.

List Events

HTTP Request

GET /api/events

GET /api/events HTTP/1.1
X-Access-Token: username:token

Response

[
    {
        "type": "api",
        "container_info": {
            "Id": "",
            "Created": "",
            "Path": "",
            "Name": "",
            "Args": null,
            "ExecIDs": null,
            "Config": null,
            "State": {
                "Running": false,
                "Paused": false,
                "Restarting": false,
                "Pid": 0,
                "ExitCode": 0,
                "StartedAt": "0001-01-01T00:00:00Z",
                "FinishedAt": "0001-01-01T00:00:00Z",
                "Ghost": false
            },
            "Image": "",
            "NetworkSettings": {
                "IpAddress": "",
                "IpPrefixLen": 0,
                "Gateway": "",
                "Bridge": "",
                "Ports": null
            },
            "SysInitPath": "",
            "ResolvConfPath": "",
            "Volumes": null,
            "HostConfig": null
        },
        "time": "2015-06-27T19:04:33Z",
        "message": "/api/accounts",
        "username": "admin",
        "tags": [
            "api",
            "api",
            "get"
        ]
    }
]

Delete all Events

HTTP Request

DELETE /api/events

This will delete all events.

DELETE /api/events HTTP/1.1
X-Access-Token: username:token

Response

HTTP/1.1 204 No Content

Help

Having trouble getting started? Please do not hesitate to reach out. We are truly greatful for our wonderful community and love helping! Feel free to use whatever medium works best for you:
GitHub: https://github.com/shipyard/shipyard
IRC: #shipyard on Freenode