docs/sources/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
~~~~~~~~~

.. http:put:: /v1/repositories/(namespace)/(repo_name)/

    Create a user repository with the given ``namespace`` and ``repo_name``.

    **Example Request**:

    .. sourcecode:: http

        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**:

    .. sourcecode:: http

        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


.. http:delete:: /v1/repositories/(namespace)/(repo_name)/

    Delete a user repository with the given ``namespace`` and ``repo_name``.

    **Example Request**:

    .. sourcecode:: http

        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**:

    .. sourcecode:: http

        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
~~~~~~~~~~~~

.. http:put:: /v1/repositories/(repo_name)/

    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**:

    .. sourcecode:: http

        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**:

    .. sourcecode:: http

        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

.. http:delete:: /v1/repositories/(repo_name)/

    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**:

    .. sourcecode:: http

        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**:

    .. sourcecode:: http

        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
~~~~~~~~~~~~~~~~

.. http:put:: /v1/repositories/(namespace)/(repo_name)/images

    Update the images for a user repo.

    **Example Request**:

    .. sourcecode:: http

        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**:

    .. sourcecode:: http

        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


.. http:get:: /v1/repositories/(namespace)/(repo_name)/images

    get the images for a user repo.

    **Example Request**:

    .. sourcecode:: http

        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**:

    .. sourcecode:: http

        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
~~~~~~~~~~~~~~~~~~~

.. http:put:: /v1/repositories/(repo_name)/images

    Update the images for a library repo.

    **Example Request**:

    .. sourcecode:: http

        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**:

    .. sourcecode:: http

        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


.. http:get:: /v1/repositories/(repo_name)/images

    get the images for a library repo.

    **Example Request**:

    .. sourcecode:: http

        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**:

    .. sourcecode:: http

        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
~~~~~~~~~~~~

.. http:put:: /v1/repositories/(repo_name)/auth

    authorize a token for a library repo

    **Example Request**:

    .. sourcecode:: http

        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**:

    .. sourcecode:: http

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

        "OK"

    :statuscode 200: OK
    :statuscode 403: Permission denied
    :statuscode 404: Not found


User Repo
~~~~~~~~~

.. http:put:: /v1/repositories/(namespace)/(repo_name)/auth

    authorize a token for a user repo

    **Example Request**:

    .. sourcecode:: http

        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**:

    .. sourcecode:: http

        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
**********

.. http:get:: /v1/users

    If you want to check your login, you can try this endpoint
    
    **Example Request**:
    
    .. sourcecode:: http
    
        GET /v1/users HTTP/1.1
        Host: index.docker.io
        Accept: application/json
        Authorization: Basic akmklmasadalkm==

    **Example Response**:

    .. sourcecode:: http

        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
*************

.. http:post:: /v1/users

    Registering a new account.

    **Example request**:

    .. sourcecode:: http

        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**:

    .. sourcecode:: http

        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
***********

.. http:put:: /v1/users/(username)/

    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**:

    .. sourcecode:: http

        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**:

    .. sourcecode:: http

        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
******

.. http:get:: /v1/search

   Search the Index given a search term. It accepts :http:method:`get` only.

   **Example request**:

   .. sourcecode:: http

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


   **Example response**:

   .. sourcecode:: http

      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