mobi/moby
1
0
Fork 0
mirror of https://github.com/moby/moby.git synced 2025-12-06 07:41:18 +03:00
Code Activity
Files
ac999a9cb2b0976e021aeb8825bb051df6bd0976
moby/docs/sources/reference/api/docker_io_accounts_api.rst
Sven Dowideit a777ebcee6 move the documentation to markdown 
Docker-DCO-1.1-Signed-off-by: Sven Dowideit <SvenDowideit@home.org.au> (github: SvenDowideit)
2014-04-16 11:04:01 +10:00

9.8 KiB
Raw Blame History

title
docker.io Accounts API
description
API Documentation for docker.io accounts.
keywords
API, Docker, accounts, REST, documentation

docker.io Accounts API

1. Endpoints

1.1 Get a single user

Get profile info for the specified user.

param username
username of the user whose profile info is being requested.
reqheader Authorization
required authentication credentials of either type HTTP Basic or OAuth Bearer Token.
statuscode 200
success, user data returned.
statuscode 401
authentication error.
statuscode 403
permission error, authenticated user must be the user whose data is being requested, OAuth access tokens must have profile_read scope.
statuscode 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

Update profile info for the specified user.

param username
username of the user whose profile info is being updated.
jsonparam string full_name
(optional) the new name of the user.
jsonparam string location
(optional) the new location.
jsonparam string company
(optional) the new company of the user.
jsonparam string profile_url
(optional) the new profile url.
jsonparam string gravatar_email
(optional) the new Gravatar email address.
reqheader Authorization
required authentication credentials of either type HTTP Basic or OAuth Bearer Token.
reqheader Content-Type
MIME Type of post data. JSON, url-encoded form data, etc.
statuscode 200
success, user data updated.
statuscode 400
post data validation error.
statuscode 401
authentication error.
statuscode 403
permission error, authenticated user must be the user whose data is being updated, OAuth access tokens must have profile_write scope.
statuscode 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

List email info for the specified user.

param username
username of the user whose profile info is being updated.
reqheader Authorization
required authentication credentials of either type HTTP Basic or OAuth Bearer Token
statuscode 200
success, user data updated.
statuscode 401
authentication error.
statuscode 403
permission error, authenticated user must be the user whose data is being requested, OAuth access tokens must have email_read scope.
statuscode 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

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.

jsonparam string email
email address to be added.
reqheader Authorization
required authentication credentials of either type HTTP Basic or OAuth Bearer Token.
reqheader Content-Type
MIME Type of post data. JSON, url-encoded form data, etc.
statuscode 201
success, new email added.
statuscode 400
data validation error.
statuscode 401
authentication error.
statuscode 403
permission error, authenticated user must be the user whose data is being requested, OAuth access tokens must have email_write scope.
statuscode 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

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.

param username
username of the user whose email info is being updated.
jsonparam string email
the email address to be updated.
jsonparam boolean verified
(optional) whether the email address is verified, must be true or absent.
jsonparam boolean primary
(optional) whether to set the email address as the primary email, must be true or absent.
reqheader Authorization
required authentication credentials of either type HTTP Basic or OAuth Bearer Token.
reqheader Content-Type
MIME Type of post data. JSON, url-encoded form data, etc.
statuscode 200
success, user's email updated.
statuscode 400
data validation error.
statuscode 401
authentication error.
statuscode 403
permission error, authenticated user must be the user whose data is being updated, OAuth access tokens must have email_write scope.
statuscode 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 an email address from the specified user's account. You cannot delete a user's primary email address.

jsonparam string email
email address to be deleted.
reqheader Authorization
required authentication credentials of either type HTTP Basic or OAuth Bearer Token.
reqheader Content-Type
MIME Type of post data. JSON, url-encoded form data, etc.
statuscode 204
success, email address removed.
statuscode 400
validation error.
statuscode 401
authentication error.
statuscode 403
permission error, authenticated user must be the user whose data is being requested, OAuth access tokens must have email_write scope.
statuscode 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
View Git Blame Copy Permalink