diff --git a/_data/toc.yaml b/_data/toc.yaml index a33bab9577..d9705038a2 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -5,6 +5,8 @@ toc: section: - path: /docker-id/ title: Docker ID accounts + - path: /docker-id/api-reference/ + title: API Reference - sectiontitle: Docker Engine section: - sectiontitle: Install @@ -495,8 +497,6 @@ toc: title: Remote API v1.18 - path: /engine/reference/api/remote_api_client_libraries/ title: Remote API client libraries - - path: /engine/reference/api/docker_io_accounts_api/ - title: docker.io accounts API - path: /engine/migration/ title: Migrate to Engine 1.10 - path: /engine/breaking_changes/ diff --git a/docker-id/api-reference.md b/docker-id/api-reference.md new file mode 100644 index 0000000000..6fd08d4a7b --- /dev/null +++ b/docker-id/api-reference.md @@ -0,0 +1,277 @@ +--- +title: "docker.io accounts API" +description: "API Documentation for docker.io accounts." +keywords: "API, Docker, accounts, REST, documentation" +redirect_from: + - /reference/api/docker_io_accounts_api/ + - /engine/reference/api/docker_io_accounts_api/ +--- + +# Docker ID accounts API + +The accounts API is an API for accessing and updating Docker ID accounts. + +## 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 + } + +## 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 + } + +## 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 + } + ] + +## 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 + } + +## 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