O.S.Tezer c932667cd2 Docs auto-conversion fixes and MD marking and structure improvements.

- Remove redundant chars and all errors caused by RST->MD conversion.
   e.g. [/#, /\, \<, />, etc.]
 - Fix broken inter-document links
 - Fix outbound links no-longer active or changed
 - Fix lists
 - Fix code blocks
 - Correct apostrophes
 - Replace redundant inline note marks for code with code marks
 - Fix broken image links
 - Remove non-functional title links
 - Correct broken cross-docs links
 - Improve readability

Note: This PR does not try to fix/amend:

 - Grammatical errors
 - Lexical errors
 - Linguistic-logic errors etc.

It just aims to fix main structural or conversion errors to serve as
a base for further amendments that will cover others including but
not limited to those mentioned above.

Docker-DCO-1.1-Signed-off-by: O.S. Tezer <ostezer@gmail.com> (github: ostezer)

Update:

 - Fix backtick issues

Docker-DCO-1.1-Signed-off-by: Sven Dowideit <SvenDowideit@home.org.au> (github: SvenDowideit)

2014-04-24 22:19:32 +10:00

9.9 KiB

Raw Blame History

page_title: docker.io Accounts API page_description: API Documentation for docker.io accounts. page_keywords: API, Docker, accounts, REST, documentation

docker.io Accounts API

1. Endpoints

1.1 Get a single user

GET /api/v1.1/users/:username/

Get profile info for the specified user.

Parameters:

-   **username** – username of the user whose profile info is being
    requested.

Request Headers:

 

-   **Authorization** – required authentication credentials of
    either type HTTP Basic or OAuth Bearer Token.

Status Codes:

-   **200** – success, user data returned.
-   **401** – authentication error.
-   **403** – permission error, authenticated user must be the user
    whose data is being requested, OAuth access tokens must have
    `profile_read` scope.
-   **404** – the specified username does not exist.

**Example request**:

    GET /api/v1.1/users/janedoe/ HTTP/1.1
    Host: www.docker.io
    Accept: application/json
    Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

**Example response**:

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

    {
        "id": 2,
        "username": "janedoe",
        "url": "https://www.docker.io/api/v1.1/users/janedoe/",
        "date_joined": "2014-02-12T17:58:01.431312Z",
        "type": "User",
        "full_name": "Jane Doe",
        "location": "San Francisco, CA",
        "company": "Success, Inc.",
        "profile_url": "https://docker.io/",
        "gravatar_url": "https://secure.gravatar.com/avatar/0212b397124be4acd4e7dea9aa357.jpg?s=80&r=g&d=mm"
        "email": "jane.doe@example.com",
        "is_active": true
    }

1.2 Update a single user

PATCH /api/v1.1/users/:username/

Update profile info for the specified user.

Parameters:

-   **username** – username of the user whose profile info is being
    updated.

Json Parameters:

 

-   **full_name** (*string*) – (optional) the new name of the user.
-   **location** (*string*) – (optional) the new location.
-   **company** (*string*) – (optional) the new company of the user.
-   **profile_url** (*string*) – (optional) the new profile url.
-   **gravatar_email** (*string*) – (optional) the new Gravatar
    email address.

Request Headers:

 

-   **Authorization** – required authentication credentials of
    either type HTTP Basic or OAuth Bearer Token.
-   **Content-Type** – MIME Type of post data. JSON, url-encoded
    form data, etc.

Status Codes:

-   **200** – success, user data updated.
-   **400** – post data validation error.
-   **401** – authentication error.
-   **403** – permission error, authenticated user must be the user
    whose data is being updated, OAuth access tokens must have
    `profile_write` scope.
-   **404** – the specified username does not exist.

**Example request**:

    PATCH /api/v1.1/users/janedoe/ HTTP/1.1
    Host: www.docker.io
    Accept: application/json
    Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

    {
        "location": "Private Island",
        "profile_url": "http://janedoe.com/",
        "company": "Retired",
    }

**Example response**:

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

    {
        "id": 2,
        "username": "janedoe",
        "url": "https://www.docker.io/api/v1.1/users/janedoe/",
        "date_joined": "2014-02-12T17:58:01.431312Z",
        "type": "User",
        "full_name": "Jane Doe",
        "location": "Private Island",
        "company": "Retired",
        "profile_url": "http://janedoe.com/",
        "gravatar_url": "https://secure.gravatar.com/avatar/0212b397124be4acd4e7dea9aa357.jpg?s=80&r=g&d=mm"
        "email": "jane.doe@example.com",
        "is_active": true
    }

1.3 List email addresses for a user

GET /api/v1.1/users/:username/emails/

List email info for the specified user.

Parameters:

-   **username** – username of the user whose profile info is being
    updated.

Request Headers:

 

-   **Authorization** – required authentication credentials of
    either type HTTP Basic or OAuth Bearer Token

Status Codes:

-   **200** – success, user data updated.
-   **401** – authentication error.
-   **403** – permission error, authenticated user must be the user
    whose data is being requested, OAuth access tokens must have
    `email_read` scope.
-   **404** – the specified username does not exist.

**Example request**:

    GET /api/v1.1/users/janedoe/emails/ HTTP/1.1
    Host: www.docker.io
    Accept: application/json
    Authorization: Bearer zAy0BxC1wDv2EuF3tGs4HrI6qJp6KoL7nM

**Example response**:

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

    [
        {
            "email": "jane.doe@example.com",
            "verified": true,
            "primary": true
        }
    ]

1.4 Add email address for a user

POST /api/v1.1/users/:username/emails/

Add a new email address to the specified user's account. The email address must be verified separately, a confirmation email is not automatically sent.

Json Parameters:

 

-   **email** (*string*) – email address to be added.

Request Headers:

 

-   **Authorization** – required authentication credentials of
    either type HTTP Basic or OAuth Bearer Token.
-   **Content-Type** – MIME Type of post data. JSON, url-encoded
    form data, etc.

Status Codes:

-   **201** – success, new email added.
-   **400** – data validation error.
-   **401** – authentication error.
-   **403** – permission error, authenticated user must be the user
    whose data is being requested, OAuth access tokens must have
    `email_write` scope.
-   **404** – the specified username does not exist.

**Example request**:

    POST /api/v1.1/users/janedoe/emails/ HTTP/1.1
    Host: www.docker.io
    Accept: application/json
    Content-Type: application/json
    Authorization: Bearer zAy0BxC1wDv2EuF3tGs4HrI6qJp6KoL7nM

    {
        "email": "jane.doe+other@example.com"
    }

**Example response**:

    HTTP/1.1 201 Created
    Content-Type: application/json

    {
        "email": "jane.doe+other@example.com",
        "verified": false,
        "primary": false
    }

1.5 Update an email address for a user

PATCH /api/v1.1/users/:username/emails/

Update an email address for the specified user to either verify an email address or set it as the primary email for the user. You cannot use this endpoint to un-verify an email address. You cannot use this endpoint to unset the primary email, only set another as the primary.

Parameters:

-   **username** – username of the user whose email info is being
    updated.

Json Parameters:

 

-   **email** (*string*) – the email address to be updated.
-   **verified** (*boolean*) – (optional) whether the email address
    is verified, must be `true` or absent.
-   **primary** (*boolean*) – (optional) whether to set the email
    address as the primary email, must be `true`
    or absent.

Request Headers:

 

-   **Authorization** – required authentication credentials of
    either type HTTP Basic or OAuth Bearer Token.
-   **Content-Type** – MIME Type of post data. JSON, url-encoded
    form data, etc.

Status Codes:

-   **200** – success, user's email updated.
-   **400** – data validation error.
-   **401** – authentication error.
-   **403** – permission error, authenticated user must be the user
    whose data is being updated, OAuth access tokens must have
    `email_write` scope.
-   **404** – the specified username or email address does not
    exist.

**Example request**:

Once you have independently verified an email address.

    PATCH /api/v1.1/users/janedoe/emails/ HTTP/1.1
    Host: www.docker.io
    Accept: application/json
    Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

    {
        "email": "jane.doe+other@example.com",
        "verified": true,
    }

**Example response**:

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

    {
        "email": "jane.doe+other@example.com",
        "verified": true,
        "primary": false
    }

1.6 Delete email address for a user

DELETE /api/v1.1/users/:username/emails/

Delete an email address from the specified user's account. You cannot delete a user's primary email address.

Json Parameters:

 

-   **email** (*string*) – email address to be deleted.

Request Headers:

 

-   **Authorization** – required authentication credentials of
    either type HTTP Basic or OAuth Bearer Token.
-   **Content-Type** – MIME Type of post data. JSON, url-encoded
    form data, etc.

Status Codes:

-   **204** – success, email address removed.
-   **400** – validation error.
-   **401** – authentication error.
-   **403** – permission error, authenticated user must be the user
    whose data is being requested, OAuth access tokens must have
    `email_write` scope.
-   **404** – the specified username or email address does not
    exist.

**Example request**:

    DELETE /api/v1.1/users/janedoe/emails/ HTTP/1.1
    Host: www.docker.io
    Accept: application/json
    Content-Type: application/json
    Authorization: Bearer zAy0BxC1wDv2EuF3tGs4HrI6qJp6KoL7nM

    {
        "email": "jane.doe+other@example.com"
    }

**Example response**:

    HTTP/1.1 204 NO CONTENT
    Content-Length: 0

9.9 KiB Raw Blame History Unescape Escape