moby/docs/sources/reference/api/index_api.rst

title

Index API

description

API Documentation for Docker Index

keywords

API, Docker, index, REST, documentation

Docker Index API

1. Brief introduction

• This is the REST API for the Docker index
• Authorization is done with basic auth over SSL
• Not all commands require authentication, only those noted as such.

2. Endpoints

2.1 Repository

Repositories

User Repo

Create a user repository with the given namespace and repo_name.

Example Request:

PUT /v1/repositories/foo/bar/ HTTP/1.1
Host: index.docker.io
Accept: application/json
Content-Type: application/json
Authorization: Basic akmklmasadalkm==
X-Docker-Token: true

[{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f"}]

parameter namespace

the namespace for the repo

parameter repo_name

the name for the repo

Example Response:

HTTP/1.1 200
Vary: Accept
Content-Type: application/json
WWW-Authenticate: Token signature=123abc,repository="foo/bar",access=write
X-Docker-Token: signature=123abc,repository="foo/bar",access=write
X-Docker-Endpoints: registry-1.docker.io [, registry-2.docker.io]

""

statuscode 200

Created

statuscode 400

Errors (invalid json, missing or invalid fields, etc)

statuscode 401

Unauthorized

statuscode 403

Account is not Active

Delete a user repository with the given namespace and repo_name.

Example Request:

DELETE /v1/repositories/foo/bar/ HTTP/1.1
Host: index.docker.io
Accept: application/json
Content-Type: application/json
Authorization: Basic akmklmasadalkm==
X-Docker-Token: true

""

parameter namespace

the namespace for the repo

parameter repo_name

the name for the repo

Example Response:

HTTP/1.1 202
Vary: Accept
Content-Type: application/json
WWW-Authenticate: Token signature=123abc,repository="foo/bar",access=delete
X-Docker-Token: signature=123abc,repository="foo/bar",access=delete
X-Docker-Endpoints: registry-1.docker.io [, registry-2.docker.io]

""

statuscode 200

Deleted

statuscode 202

Accepted

statuscode 400

Errors (invalid json, missing or invalid fields, etc)

statuscode 401

Unauthorized

statuscode 403

Account is not Active

Library Repo

Create a library repository with the given repo_name. This is a restricted feature only available to docker admins.

When namespace is missing, it is assumed to be library

Example Request:

PUT /v1/repositories/foobar/ HTTP/1.1
Host: index.docker.io
Accept: application/json
Content-Type: application/json
Authorization: Basic akmklmasadalkm==
X-Docker-Token: true

[{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f"}]

parameter repo_name

the library name for the repo

Example Response:

HTTP/1.1 200
Vary: Accept
Content-Type: application/json
WWW-Authenticate: Token signature=123abc,repository="library/foobar",access=write
X-Docker-Token: signature=123abc,repository="foo/bar",access=write
X-Docker-Endpoints: registry-1.docker.io [, registry-2.docker.io]

""

statuscode 200

Created

statuscode 400

Errors (invalid json, missing or invalid fields, etc)

statuscode 401

Unauthorized

statuscode 403

Account is not Active

Delete a library repository with the given repo_name. This is a restricted feature only available to docker admins.

When namespace is missing, it is assumed to be library

Example Request:

DELETE /v1/repositories/foobar/ HTTP/1.1
Host: index.docker.io
Accept: application/json
Content-Type: application/json
Authorization: Basic akmklmasadalkm==
X-Docker-Token: true

""

parameter repo_name

the library name for the repo

Example Response:

HTTP/1.1 202
Vary: Accept
Content-Type: application/json
WWW-Authenticate: Token signature=123abc,repository="library/foobar",access=delete
X-Docker-Token: signature=123abc,repository="foo/bar",access=delete
X-Docker-Endpoints: registry-1.docker.io [, registry-2.docker.io]

""

statuscode 200

Deleted

statuscode 202

Accepted

statuscode 400

Errors (invalid json, missing or invalid fields, etc)

statuscode 401

Unauthorized

statuscode 403

Account is not Active

Repository Images

User Repo Images

Update the images for a user repo.

Example Request:

PUT /v1/repositories/foo/bar/images HTTP/1.1
Host: index.docker.io
Accept: application/json
Content-Type: application/json
Authorization: Basic akmklmasadalkm==

[{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f",
"checksum": "b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087"}]

parameter namespace

the namespace for the repo

parameter repo_name

the name for the repo

Example Response:

HTTP/1.1 204
Vary: Accept
Content-Type: application/json

""

statuscode 204

Created

statuscode 400

Errors (invalid json, missing or invalid fields, etc)

statuscode 401

Unauthorized

statuscode 403

Account is not Active or permission denied

get the images for a user repo.

Example Request:

GET /v1/repositories/foo/bar/images HTTP/1.1
Host: index.docker.io
Accept: application/json

parameter namespace

the namespace for the repo

parameter repo_name

the name for the repo

Example Response:

HTTP/1.1 200
Vary: Accept
Content-Type: application/json

[{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f",
"checksum": "b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087"},
{"id": "ertwetewtwe38722009fe6857087b486531f9a779a0c1dfddgfgsdgdsgds",
"checksum": "34t23f23fc17e3ed29dae8f12c4f9e89cc6f0bsdfgfsdgdsgdsgerwgew"}]

statuscode 200

OK

statuscode 404

Not found

Library Repo Images

Update the images for a library repo.

Example Request:

PUT /v1/repositories/foobar/images HTTP/1.1
Host: index.docker.io
Accept: application/json
Content-Type: application/json
Authorization: Basic akmklmasadalkm==

[{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f",
"checksum": "b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087"}]

parameter repo_name

the library name for the repo

Example Response:

HTTP/1.1 204
Vary: Accept
Content-Type: application/json

""

statuscode 204

Created

statuscode 400

Errors (invalid json, missing or invalid fields, etc)

statuscode 401

Unauthorized

statuscode 403

Account is not Active or permission denied

get the images for a library repo.

Example Request:

GET /v1/repositories/foobar/images HTTP/1.1
Host: index.docker.io
Accept: application/json

parameter repo_name

the library name for the repo

Example Response:

HTTP/1.1 200
Vary: Accept
Content-Type: application/json

[{"id": "9e89cc6f0bc3c38722009fe6857087b486531f9a779a0c17e3ed29dae8f12c4f",
"checksum": "b486531f9a779a0c17e3ed29dae8f12c4f9e89cc6f0bc3c38722009fe6857087"},
{"id": "ertwetewtwe38722009fe6857087b486531f9a779a0c1dfddgfgsdgdsgds",
"checksum": "34t23f23fc17e3ed29dae8f12c4f9e89cc6f0bsdfgfsdgdsgdsgerwgew"}]

statuscode 200

OK

statuscode 404

Not found

Repository Authorization

Library Repo

authorize a token for a library repo

Example Request:

PUT /v1/repositories/foobar/auth HTTP/1.1
Host: index.docker.io
Accept: application/json
Authorization: Token signature=123abc,repository="library/foobar",access=write

parameter repo_name

the library name for the repo

Example Response:

HTTP/1.1 200
Vary: Accept
Content-Type: application/json

"OK"

statuscode 200

OK

statuscode 403

Permission denied

statuscode 404

Not found

User Repo

authorize a token for a user repo

Example Request:

PUT /v1/repositories/foo/bar/auth HTTP/1.1
Host: index.docker.io
Accept: application/json
Authorization: Token signature=123abc,repository="foo/bar",access=write

parameter namespace

the namespace for the repo

parameter repo_name

the name for the repo

Example Response:

HTTP/1.1 200
Vary: Accept
Content-Type: application/json

"OK"

statuscode 200

OK

statuscode 403

Permission denied

statuscode 404

Not found

2.2 Users

User Login

If you want to check your login, you can try this endpoint

Example Request:

GET /v1/users HTTP/1.1
Host: index.docker.io
Accept: application/json
Authorization: Basic akmklmasadalkm==

Example Response:

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

OK

statuscode 200

no error

statuscode 401

Unauthorized

statuscode 403

Account is not Active

User Register

Registering a new account.

Example request:

POST /v1/users HTTP/1.1
Host: index.docker.io
Accept: application/json
Content-Type: application/json

{"email": "sam@dotcloud.com",
 "password": "toto42",
 "username": "foobar"'}

jsonparameter email

valid email address, that needs to be confirmed

jsonparameter username

min 4 character, max 30 characters, must match the regular expression [a-z0-9_].

jsonparameter password

min 5 characters

Example Response:

HTTP/1.1 201 OK
Vary: Accept
Content-Type: application/json

"User Created"

statuscode 201

User Created

statuscode 400

Errors (invalid json, missing or invalid fields, etc)

Update User

Change a password or email address for given user. If you pass in an email, it will add it to your account, it will not remove the old one. Passwords will be updated.

It is up to the client to verify that that password that is sent is the one that they want. Common approach is to have them type it twice.

Example Request:

PUT /v1/users/fakeuser/ HTTP/1.1
Host: index.docker.io
Accept: application/json
Content-Type: application/json
Authorization: Basic akmklmasadalkm==

{"email": "sam@dotcloud.com",
 "password": "toto42"}

parameter username

username for the person you want to update

Example Response:

HTTP/1.1 204
Vary: Accept
Content-Type: application/json

""

statuscode 204

User Updated

statuscode 400

Errors (invalid json, missing or invalid fields, etc)

statuscode 401

Unauthorized

statuscode 403

Account is not Active

statuscode 404

User not found

2.3 Search

If you need to search the index, this is the endpoint you would use.

Search

Search the Index given a search term. It accepts get only.

Example request:

GET /v1/search?q=search_term HTTP/1.1
Host: example.com
Accept: application/json

Example response:

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

{"query":"search_term",
  "num_results": 3,
  "results" : [
     {"name": "ubuntu", "description": "An ubuntu image..."},
     {"name": "centos", "description": "A centos image..."},
     {"name": "fedora", "description": "A fedora image..."}
   ]
 }

query q

what you want to search for

statuscode 200

no error

statuscode 500

server error