mirror of https://github.com/moby/moby.git synced 2022-11-09 12:21:53 -05:00

Josh Hawn c6060a3b25 Added back OAuth and Accounts API docs pages

Removed a now unused endpoint from the accounts API.
Updated some of the accounts links to point to www.docker.io
as the account signup and resend-email-confirmation links should
no longer point to the index.

Docker-DCO-1.1-Signed-off-by: Josh Hawn <josh.hawn@docker.com> (github: jlhawn)

2014-04-27 11:17:48 -07:00

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

7.9 KiB Raw Blame History Unescape Escape