docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

The API docs Josh wrote - with the hugo meta-data added 

Signed-off-by: Sven Dowideit <SvenDowideit@home.org.au>
This commit is contained in:
Sven Dowideit 2015-08-17 15:26:15 +10:00
parent 1bd00d9a53
commit 67ee0b2bf2
8 changed files with 1514 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

368
api/dtr_1_3_accounts.md Executable file
View File

@ -0,0 +1,368 @@
+++
title = "DTR accounts API"
description = "Docker Trusted Registry 1.3 User and Organization Accounts"
keywords = ["API, Docker, index, REST, documentation, Docker Trusted Registry, registry"]
weight = 61
[menu.main]
parent = "smn_remoteapi"
+++
# Docker Trusted Registry 1.3 User and Organization Accounts
## Create an Account
`POST /api/v0/accounts`
### Create a Managed User Account
DTR auth settings must be in "managed" mode.
Example Request:
```http
POST /api/v0/accounts HTTP/1.1
Content-Type: application/json
{
"type": "user",
"name": "alice",
"password": "watchThinkFruitNeighbor"
}
```
Response:
```json
{
"id": 3,
"type": "user",
"name": "alice",
"isActive": false
}
```
**Authorization**
Anyone may create a managed user account, however managed user accounts start
out inactive and the user cannot authenticate until an admin explicitly
activates the user account using the activate user API endpoint.
**Status Codes**
- *400* invalid input.
- *200* success.
### Create a User Account from LDAP
DTR auth settings must be in "ldap" mode.
Example Request:
```http
POST /api/v0/accounts HTTP/1.1
Content-Type: application/json
{
"type": "user",
"name": "robert.smith",
"ldapLogin": "robert.smith",
"password": "shakeMeanPlainBaseball"
}
```
The `name` field is the requested username to use in DTR while `ldapLogin`
should be the user's LDAP user login attribute. These need only differ if the
user prefers or if the user's LDAP login name is not compatible with valid DTR
usernames.
Response:
```json
{
"id": 4,
"type": "user",
"name": "robert.smith",
"ldapLogin": "robert.smith"
}
```
**Authorization**
Anyone may create an LDAP user account, however, the account is only created if
the client provides a valid ldap login and password.
**Status Codes**
- *400* invalid input.
- *200* success.
### Create an Organization Account
DTR auth settings must be in "managed" or "ldap" mode.
Example Request:
```http
POST /api/v0/accounts HTTP/1.1
Content-Type: application/json
{
"type": "organization",
"name": "engineering"
}
```
Response:
```json
{
"id": 5,
"type": "organization",
"name": "engineering",
"ldapLogin": "engineering"
}
```
**Authorization**
Client must be authenticated as a global 'admin' user.
**Status Codes**
- *400* invalid input.
- *401* client must be authenticated.
- *403* client must be an admin.
- *200* success.
## List Accounts
`GET /api/v0/accounts`
Example Response:
```json
{
"accounts": [
{
"id": 1,
"type": "user",
"name": "admin",
"isActive": true
},
{
"id": 2,
"type": "user",
"name": "jlhawn",
"isActive": true
},
{
"id": 3,
"type": "user",
"name": "alice",
"isActive": true
},
{
"id": 4,
"type": "organization",
"name": "engineering",
}
]
}
```
**Authorization**
Client must be authenticated as any user in the system.
**Status Codes**
- *401* the client is not authenticated.
- *200* success.
## Account Details
`GET /api/v0/accounts/{name}`
Example Request:
```http
GET /api/v0/accounts/alice HTTP/1.1
```
Response:
```json
{
"id": 3,
"type": "user",
"name": "alice",
"isActive": true
}
```
**Authorization**
Client must be authenticated as any user in the system.
**Status Codes**
- *404* no such account exists.
- *401* the client is not authenticated.
- *200* success.
## Remove an Account
`DELETE /api/v0/accounts/{name}`
Example Request:
```http
DELETE /api/v0/accounts/alice HTTP/1.1
```
**Authorization**
Client must be authenticated as a system 'admin' user.
**Status Codes**
- *401* client must be authenticated.
- *403* client must be an admin.
- *204* success.
## Change a Managed User's Password
`POST /api/v0/accounts/{name}/changePassword`
Example Request:
```http
POST /api/v0/accounts/alice/changePassword HTTP/1.1
Content-Type: application/json
{
"oldPassword": "watchThinkFruitNeighbor",
"newPassword": "pinkCloudBehaviorDozen"
}
```
Response:
```json
{
"id": 5,
"type": "user",
"name": "alice",
"isActive": true
}
```
**Authorization**
Client must be authenticated as the user in question or as an admin user (in
which case the `oldPassword` field may be omitted from the request body.
**Status Codes**
- *400* invalid input.
- *401* client must be authenticated.
- *200* success.
## Activate a Managed User
`PUT /api/v0/accounts/{name}/activate`
Example Request:
```http
PUT /api/v0/accounts/alice/activate HTTP/1.1
```
Response:
```json
{
"id": 5,
"type": "user",
"name": "alice",
"isActive": true
}
```
**Authorization**
Client must be authenticated as a system 'admin' user.
**Status Codes**
- *404* no such account.
- *401* client must be authenticated.
- *403* client must be an admin.
- *200* success.
## Deactivate a Managed User
`PUT /api/v0/accounts/{name}/deactivate`
Example Request:
```http
PUT /api/v0/accounts/alice/deactivate HTTP/1.1
```
Examlpe Response:
```json
{
"id": 5,
"type": "user",
"name": "alice",
"isActive": true
}
```
**Authorization**
Client must be authenticated as a system 'admin' user.
**Status Codes**
- *404* no such account.
- *401* client must be authenticated.
- *403* client must be an admin.
- *200* success.
## List Organizations for a User
`GET /api/v0/accounts/{name}/organizations`
Example Request:
```http
GET /api/v0/accounts/alice/organizations HTTP/1.1
```
Example Response:
```json
{
"organizations": [
{
"id": 4,
"type": "organization",
"name": "engineering",
}
]
}
```
**Authorization**
Client must be authenticated as a system 'admin' user or the user in question.
**Status Codes**
- *404* no such account.
- *401* client must be authenticated.
- *403* client must be an admin or target user.
- *200* success.

140
api/dtr_1_3_design_doc.md Executable file
View File

@ -0,0 +1,140 @@
+++
title = "DTR API Design document"
description = "DTR 1.3 API Design document"
draft = true
keywords = ["API, Docker, index, REST, documentation, Docker Trusted Registry, registry"]
[menu.main]
parent = "smn_remoteapi"
+++
# Docker Trusted Registry 1.3
## Organization Accounts and Repository Access Control
We need an API for fine-grained role based access control in Docker Trusted
Registry.
### Goals
1. An API for managing accounts
This includes creating an account, listing existing accounts, creating a
team within an organization, listing teamns in an organization, getting a
specific team, listing members of a team, adding and removing members
from a team (if managed whitelist) or editing ldap sync config.
2. LDAP Syncing
We need to be able to automatically sync members of a team according to
some LDAP group filter configured by an org admin.
3. An API for repositories and access control.
This includes creating a repository, listing repositories for an account,
adding collaborators to a repository, setting namespace-level access for
teams, etc.
4. Minimal or No Data Migration.
If we can help it, we’d like to not require any data migration in this
release, only schema migration.
### Non-Goals
No UI. This release will be API only.
### Design
There are two types of accounts: Users and Organizations. We will be creating a
sense of account-owned namespaces in DTR much like in Docker Hub Registry.
Account-owned (non-global) repositories will have two-component names of the
form `namespace/reponame`.
Users will be able to create a repository under their own namespace and be able
to control what other users have read-only, read-write, or admin access to any
of their repositories.
System administrators can also create an Organization account, with it’s own
namespace of repositories. Organization accounts will have one or more teams
which can be managed by anyone in the initial ‘owners’ team. Teams can either
be created with a managed whitelist of users known to the system or with an
LDAP group search filter which will be periodically synced.
Any member of an organization’s owners team can create new repositories under
the organization’s namespace and even create and edit other teams. Each team
can be given read-only or read-write access to all repositories in the
organization’s namespace and/or be granted separate levels of access on a
per-repository basis. Permissions are additive, so there is no way to override
a team level permission to prevent access to a specific repository.
Teams within an organization can also be granted read-only, read-write, or
admin level access to all repositories in the organizations namespace. This
allows a team to pull, push, and/or manage repositories for an organization
but *not* manage the teams themselves.
Repositories can be set as either public or private. Public repositories can be
read by any account in the system and only written to by accounts with explicit
write access granted to them. Private repositories will not be discoverable by
any account that does not have at least explicit read access to that
repository.
User owned repositories can only be given access to the owner and other
individual user accounts, i.e., you cannot grant access to a user-owned
repository to a team of users in an organization. If this level of control is
needed on a repository then consider moving that repository within an
organization namespace.
Organization owned repositories can only be given access to the teams within
that organization, i.e., you cannot grant access to an organization-owned
repository to an individual user account or to a team in another organization.
If this level of control is needed on a repository then consider adding those
individual users to a team within the owning organization or add users in the
other organization’s team to a team within the owning organization.
### Notable Differences from Docker Hub Registry
- Repositories must be explicitly created using the API. A `docker push` will
not create a repository if it does not exist. This prevents a typo from
creating an unwanted repository in Docker Trusted Registry. This policy
will be globally enforced in DTR 1.3.
- Organizations can only be created by system admins. This should prevent the
proliferation of unwanted organization accounts.
- Collaborators on user-owned repositories can be given more granularity of
access. Docker Hub Registry offers only read-write access. Docker Trusted
Registry plans to offer read-only, read-write, and admin access per
user-owned repository.
- Teams can be granted access to all repositories in an organization's
namespace. Docker Hub Registry offers team access control on a
per-repository level only, and only an organization's 'owners' team can
manage access and create new repositories. Docker Trusted Registry plans to
also offer the ability to grant a team access to (and/or the ability to
manage) all repositories under a namespace.
- Teams within an organization will be visible to all members of the
organization. In Docker Hub Registry, users are 'blind' to teams that they
themselves are not a member of. In Docker Trusted Registry, teams will be
visible to the members of the organization, but will not be able to see a
teams's members unless they are also a member of that team.
### API
#### Authentication
Clients may authenticate API requests by providing either Basic Auth
credentials (i.e., username and password) in an "Authorization" header for each
request.
**Accounts**
- [Accounts API Doc](https://gist.github.com/jlhawn/1e7e35c7eed536f4bdf2)
- [Teams API Doc](https://gist.github.com/jlhawn/9a1f24d44e9fce541cfb)
**Repositories**
- [Repositories API Doc](https://gist.github.com/jlhawn/dbdeb81a2724e913f036)
- [User-Owned Repository Access API Doc](https://gist.github.com/jlhawn/90e5442e1b1503b1f970)
- [Organization-Owned Repository Access API Doc](https://gist.github.com/jlhawn/45c8d6587f632975a345)
- [Organization-Owned Repository Namespace Access API Doc](https://gist.github.com/jlhawn/68f78af0e6b0325facd3)

22
api/dtr_1_3_index.md Normal file
View File

@ -0,0 +1,22 @@
+++
title = "DTR APIs"
description = "Docker Trusted Registry APIs"
keywords = ["API, Docker, index, REST, documentation, Docker Trusted Registry, registry"]
weight = 60
[menu.main]
parent = "smn_remoteapi"
+++
# Docker Trusted Registry 1.3 APIs
**Accounts**
- [Accounts API Doc]({{< relref "dtr_1_3_accounts.md" >}})
- [Teams API Doc]({{< relref "dtr_1_3_teams.md" >}})
**Repositories**
- [Repositories API Doc]({{< relref "dtr_1_3_repositories.md" >}})
- [User-Owned Repository Access API Doc]({{< relref "dtr_1_3_user_repo_access.md" >}})
- [Organization-Owned Repository Access API Doc]({{< relref "dtr_1_3_team_repo_access.md" >}})
- [Organization-Owned Repository Namespace Access API Doc]({{< relref "dtr_1_3_team_repo_namespace_access.md" >}})

180
api/dtr_1_3_repositories.md Executable file
View File

@ -0,0 +1,180 @@
+++
title = "DTR Repository API"
description = "Docker Trusted Registry 1.3 Repository API"
keywords = ["API, Docker, index, REST, documentation, Docker Trusted Registry, registry"]
weight = 65
[menu.main]
parent = "smn_remoteapi"
+++
# Docker Trusted Registry 1.3 Repositories
## Create a Repository
`POST /api/v0/repositories/{namespace}`
Example Request:
```http
POST /api/v0/repositories/alice HTTP/1.1
Content-Type: application/json
{
"name": "my-app",
"shortDescription": "My cool Docker application",
"longDescription": "This application does a bunch of cool stuff",
"visibility": "private"
}
```
Example Response:
```json
{
"id": 17,
"namespace": "alice",
"name": "my-app",
"shortDescription": "My cool Docker application",
"longDescription": "This application does a bunch of cool stuff",
"visibility": "private",
"status": "ok"
}
```
**Authorization**
Client must be authenticated as a user which has `admin` access to the
repository namespace (i.e., an owning user or member of a team with 'admin'
level access to the organization's namespace of repositories).
**Status Codes**
- *403* the client is not authorized.
- *400* invalid repository details.
- *201* success.
## Update Details of a Repository
`PATCH /api/v0/repositories/{namespace}/{reponame}`
Example Request:
```
PATCH /api/v0/repositories/alice/my-app HTTP/1.1
Content-Type: application/json
{
"shortDescription": "My Cool Docker Retro Turboencablutator",
"longDescription": "For a number of years now, work has been proceeding in order to bring perfection to the crudely conceived idea of a server application that would not only supply inverse reactive current for use in unilateral phase detractors, but would also be capable of automatically synchronizing cardinal grammeters. Such an application is this turbo-encabulator.",
"visibility": "public"
}
```
Example Response:
```json
{
"id": 17,
"namespace": "alice",
"name": "my-app",
"shortDescription": "My Cool Docker Retro Turboencablutator",
"longDescription": "For a number of years now, work has been proceeding in order to bring perfection to the crudely conceived idea of a server application that would not only supply inverse reactive current for use in unilateral phase detractors, but would also be capable of automatically synchronizing cardinal grammeters. Such an application is this turbo-encabulator.",
"visibility": "public",
"status": "ok"
}
```
**Authorization**
Client must be authenticated as a user which has `admin` access to the
repository (i.e., an owning user or member of a team with 'admin'
level access to the organization's repository).
**Status Codes**
- *403* the client is not authorized.
- *400* invalid repository details.
- *200* success.
## List Repositories in a Namespace
`GET /api/v0/repositories/{namespace}`
Example Response:
```json
{
"repositories": [
{
"id": 17,
"namespace": "don",
"name": "public-app",
"shortDescription": "An Open-Source Retro Turboencabulator",
"longDescription": "For a number of years now, work has been proceeding in order to bring perfection to the crudely conceived idea of a transmission that would not only supply inverse reactive current for use in unilateral phase detractors, but would also be capable of automatically synchronizing cardinal grammeters. Such an instrument is the turbo-encabulator.\nNow basically the only new principle involved is that instead of power being generated by the relative motion of conductors and fluxes, it's produced by the modial interaction of magneto-reluctance and capacitive diractance.",
"visibility": "public",
"status": "ok"
},
{
"id": 32,
"namespace": "don",
"name": "private-app",
"shortDescription": "A Closed-Source Retro Turboencabulator",
"longDescription": "The original machine had a base plate of pre-famulated amulite surmounted by a malleable logarithmic casing in such a way that the two spurving bearings were in a direct line with the panametric fam. The latter consisted simply of six hydrocoptic marzlevanes, so fitted to the ambifacient lunar waneshaft that side fumbling was effectively prevented.\nThe main winding was of the normal lotus-o-delta type placed in panendermic semi-boloid slots of the stator, every seventh conductor being connected by a non-reversible termie pipe to the differential girdle spring on the \"up\" end of the grammies.\nThe turbo-encabulator has now reached a high level of development, and it’s being successfully used in the operation of novertrunnions. Moreover, whenever a forescent skor motion is required, it may also be employed in conjunction with a drawn reciprocation dingle arm, to reduce soinasoidal repleneration.\nIt's not cheap, but I'm sure the government will buy it. [unfurls 50,000,000 price tag]",
"visibility": "private",
"status": "ok"
}
]
}
```
**Authorization**
Client must be authenticated as any user in the system. Results will be
filtered to only those repositories that are visible to the client.
**Status Codes**
- *404* no such repository namespace exists.
- *200* success.
## View Details of a Repositoriy
`GET /api/v0/repositories/{namespace}/{reponame}`
Example Response:
```json
{
"id": 17,
"namespace": "don",
"name": "public-app",
"shortDescription": "An Open-Source Retro Turboencabulator",
"longDescription": "For a number of years now, work has been proceeding in order to bring perfection to the crudely conceived idea of a transmission that would not only supply inverse reactive current for use in unilateral phase detractors, but would also be capable of automatically synchronizing cardinal grammeters. Such an instrument is the turbo-encabulator.\nNow basically the only new principle involved is that instead of power being generated by the relative motion of conductors and fluxes, it's produced by the modial interaction of magneto-reluctance and capacitive diractance.",
"visibility": "public",
"status": "ok"
}
```
**Authorization**
Client must be authenticated as a user which has visibility to the repository.
**Status Codes**
- *404* no such repository namespace exists or client not authorized.
- *200* success.
## Remove a Repository (removes db record only)
`DELETE /api/v0/repositories/{namespace}/{reponame}`
**Authorization**
Client must be authenticated as a user which has `admin` access to the
repository (i.e., an owning user or member of a team with 'admin'
level access to the organization's repository).
**Status Codes**
- *403* the client is not authorized.
- *204* success.

208
api/dtr_1_3_team_repo_access.md Executable file
View File

@ -0,0 +1,208 @@
+++
title = "DTR Org Repository API"
description = "Docker Trusted Registry 1.3 Organization owned Repository API"
keywords = ["API, Docker, index, REST, documentation, Docker Trusted Registry, registry"]
weight = 68
[menu.main]
parent = "smn_remoteapi"
+++
# Docker Trusted Registry 1.3 Organization-Owned Repository Access
Teams within an organization account can be granted `read-only`, `read-write`,
or `admin` level access to any repository that is owned by that organization.
**`read-only`**
- members of the team can pull from the repository
**`read-write`**
- members of the team can pull from the repository
- members of the team can push to the repository
**`admin`**
- members of the team can pull from the repository
- members of the team can push to the repository
- members of the team can manage other team's access to the repository
## List Teams Granted Access to an Organization-Owned Repository
`GET /api/v0/repositories/{namespace}/{reponame}/teamAccess`
Example Response:
```json
{
"teamAccessList": [
{
"accessLevel": "read-write",
"team": {
"id": 13,
"orgID": 22,
"type": "managed",
"name": "docs",
"description": "Documentation Team"
}
},
{
"accessLevel": "read-only",
"team": {
"id": 10,
"orgID": 22,
"type": "managed",
"name": "product",
"description": "Product Managers"
}
}
],
"repository": {
"id": 51,
"namespace": "dtr",
"name": "private-app",
"shortDescription": "A Private App for Docker Trusted Registry",
"longDescription": "We're building the next big thing - Tools of Mass Innovation",
"visibility": "private",
"status": "ok"
}
}
```
**Authorization**
Client must be authenticated as a user which has 'admin' level access to the
repository.
**Status Codes**
- *404* the repository is not visible to the client.
- *400* the repository is not owned by an organization.
- *403* the client is not authorized.
- *200* success.
## List Repository Access Grants for a Team
`GET /api/v0/accounts/{name}/teams/{teamname}/repositoryAccess`
Example Response:
```json
{
"team": {
"id": 13,
"orgID": 22,
"type": "managed",
"name": "docs",
"description": "Documentation Team"
},
"repositoryAccessList": [
{
"accessLevel": "read-write",
"repository": {
"id": 51,
"namespace": "dtr",
"name": "private-app",
"shortDescription": "A Private App for Docker Trusted Registry",
"longDescription": "We're building the next big thing - Tools of Mass Innovation",
"visibility": "private",
"status": "ok"
}
},
{
"accessLevel": "read-only",
"repository": {
"id": 52,
"namespace": "dtr",
"name": "private-app-2",
"shortDescription": "Another Private App for Docker Trusted Registry",
"longDescription": "We're still building the next big thing - Tools of Mass Innovation",
"visibility": "private",
"status": "ok"
}
}
]
}
```
**Authorization**
Client must be authenticated as a user which owns the organization the team is
in or be a member of that team.
**Status Codes**
- *404* the repository is not visible to the client.
- *400* the repository is not owned by an organization.
- *400* the team does not belong to the organization.
- *403* the client is not authorized.
- *200* success.
## Set a Team's Access to an Organization-Owned Repository
`PUT /api/v0/repositories/{namespace}/{reponame}/teamAccess/{teamname}`
Example Request:
```http
PUT /api/v0/repositories/dtr/private-app/teamAccess/13 HTTP/1.1
Content-Type: application/json
{
"accessLevel": "read-write",
}
```
Example Response:
```json
{
"accessLevel": "read-write",
"team": {
"id": 13,
"orgID": 22,
"type": "managed",
"name": "docs",
"description": "Documentation Team"
},
"repository": {
"id": 51,
"namespace": "dtr",
"name": "private-app",
"shortDescription": "A Private App for Docker Trusted Registry",
"longDescription": "We're building the next big thing - Tools of Mass Innovation",
"visibility": "private",
"status": "ok"
}
}
```
**Authorization**
Client must be authenticated as a user which has 'admin' level access to the
repository.
**Status Codes**
- *404* the repository is not visible to the client.
- *400* repository is not owned by an organization.
- *400* the team does not belong to the owning organization.
- *403* the client is unauthorized.
- *200* success.
## Revoke a Team's Access to an Organization-Owned Repository
`DELETE /api/v0/repositories/{namespace}/{reponame}/teamAccess/{teamname}`
**Authorization**
Client must be authenticated as a user which has 'admin' level access to the
repository.
**Status Codes**
- *404* the repository is not visible to the client.
- *400* the repository is not owned by an organiztion.
- *400* the team does not belong to the owning organization.
- *403* the client is not authorized.
- *200* success.

185
api/dtr_1_3_team_repo_namespace_access.md Executable file
View File

@ -0,0 +1,185 @@
+++
title = "DTR Org Namespace API"
description = "Docker Trusted Registry 1.3 Organization owned Namespace API"
keywords = ["API, Docker, index, REST, documentation, Docker Trusted Registry, registry"]
weight = 69
[menu.main]
parent = "smn_remoteapi"
+++
# Docker Trusted Registry 1.3 Organization-Owned Repository Namespace Access
Teams within an organization account can be granted `read-only`, `read-write`,
or `admin` level access to the entire namespace of repositories that are owned
by that organization.
**`read-only`**
- members of the team can pull from any repository under the organization's
namespace
**`read-write`**
- members of the team can pull from any repository under the organization's
namespace
- members of the team can push to any repository under the organization's
namespace
**`admin`**
- members of the team can pull from any repository under the organization's
namespace
- members of the team can push to any repository under the organization's
namespace
- members of the team can manage other team's access to any repository under
the organization's namespace
- members of the team can create new repositories under the organization's
namespace
## List Teams Granted Access to an Organization-Owned Namespace of Repositories
`GET /api/v0/repositoryNamespaces/{namespace}/teamAccess`
Example Response:
```json
{
"teamAccessList": [
{
"accessLevel": "read-write",
"team": {
"id": 7,
"orgID": 22,
"type": "managed",
"name": "dev",
"description": "Developers"
}
},
{
"accessLevel": "read-only",
"team": {
"id": 8,
"orgID": 22,
"type": "managed",
"name": "qa",
"description": "Quality Assurance"
}
}
],
"namespace": {
"id": 22,
"type": "organization",
"name": "engineering"
}
}
```
**Authorization**
Client must be authenticated as a user which has 'admin' level access to the
namespace.
**Status Codes**
- *400* the namespace is not owned by an organization.
- *403* the client is not authorized.
- *200* success.
## Get a Team's Granted Access to an Organization-Owned Namespace of Repositories
`GET /api/v0/repositoryNamespaces/{namespace}/teamAccess/{teamname}`
Example Response:
```json
{
"accessLevel": "read-only",
"team": {
"id": 8,
"orgID": 22,
"type": "managed",
"name": "qa",
"description": "Quality Assurance"
},
"namespace": {
"id": 22,
"type": "organization",
"name": "engineering"
}
}
```
**Authorization**
Client must be authenticated as a user which has 'admin' level access to the
namespace, is a system admin, member of the organization's "owners" team, or
is a member of the team in question.
**Status Codes**
- *400* the namespace is not owned by an organization.
- *403* the client is not authorized.
- *200* success.
## Set a Team's Access to an Organization-Owned Namespace of Repositories
`PUT /api/v0/repositoryNamespaces/{namespace}/teamAccess/{teamname}`
Example Request:
```http
PUT /api/v0/repositoryNamespaces/engineering/teamAccess/8` HTTP/1.1
Content-Type: application/json
{
"accessLevel": "read-only",
}
```
Example Response:
```json
{
"accessLevel": "read-only",
"team": {
"id": 8,
"orgID": 22,
"type": "managed",
"name": "qa",
"description": "Quality Assurance"
},
"namespace": {
"id": 22,
"type": "organization",
"name": "engineering"
}
}
```
**Authorization**
Client must be authenticated as a user which has 'admin' level access to the
namespace.
**Status Codes**
- *400* namespace is not owned by an organization.
- *400* the team does not belong to the owning organization.
- *403* the client is unauthorized.
- *200* success.
## Revoke a Team's Access to an Organization-Owned Namespace of Repositories
`DELETE /api/v0/repositoryNamespaces/{namespace}/teamAccess/{teamname}`
**Authorization**
Client must be authenticated as a user which has 'admin' level access to the
namespace.
**Status Codes**
- *400* the repository is not owned by an organiztion.
- *400* the team does not belong to the owning organization.
- *403* the client is not authorized.
- *200* success.

265
api/dtr_1_3_teams.md Executable file
View File

@ -0,0 +1,265 @@
+++
title = "DTR User and Org API"
description = "Docker Trusted Registry 1.3 User and Organization Accounts API"
keywords = ["API, Docker, index, REST, documentation, Docker Trusted Registry, registry"]
weight = 62
[menu.main]
parent = "smn_remoteapi"
+++
# Docker Trusted Registry 1.3 Teams
## Create a Team in an Organization
`POST /api/v0/accounts/{name}/teams`
Example Request:
```http
POST /api/v0/accounts/engineering/teams HTTP/1.1
Content-Type: application/json
{
"name": "qa",
"description": "QA Engineering Team",
"type": "ldap",
"ldapDN": "cn=qatesters,ou=engineering,ou=groups,dc=example,dc=com",
"ldapGroupMemberAttribute": "member"
}
```
Example Response:
```json
{
"id": 5,
"orgID": 4,
"type": "ldap",
"name": "qa",
"description": "QA Engineering Team",
"ldapDN": "cn=qatesters,ou=engineering,ou=groups,dc=example,dc=com",
"ldapGroupMemberAttribute": "member"
}
```
**Authorization**
Client must be authenticated as a system admin or a member of the "owners"
team in the organization.
**Status Codes**
- *403* the client is not authorized.
- *400* invalid team name or LDAP filter.
- *201* success.
## Update a Teams's Details
`PATCH /api/v0/accounts/{name}/teams/{teamname}`
Example Request:
```http
POST /api/v0/accounts/engineering/teams/5 HTTP/1.1
Content-Type: application/json
{
"name": "qualityassurance",
"description": "Quality Assurance Engineers"
}
```
Example Response:
```json
{
"id": 5,
"orgID": 4,
"type": "ldap",
"name": "qualityassurance",
"description": "Quality Assurance Engineers",
"ldapDN": "cn=qatesters,ou=engineering,ou=groups,dc=example,dc=com",
"ldapGroupMemberAttribute": "member"
}
```
**Authorization**
Client must be authenticated as a system admin or a member of the "owners"
team in the organization.
**Status Codes**
- *404* no such team exists.
- *403* the client is not authorized.
- *400* invalid updated detail values.
- *200* success.
## List Teams in an Organization
`GET /api/v0/accounts/{name}/teams`
Example Response:
```json
{
"teams": [
{
"id": 4,
"orgID": 4,
"type": "managed",
"name": "owners",
"description": ""
},
{
"id": 5,
"orgID": 4,
"type": "managed",
"name": "testers",
"description": "i have altered the description, pray that i do not alter it any further"
}
]
}
```
**Authorization**
Client must be authenticated as a member of the organization.
**Status Codes**
- *403* the client is not authorized.
- *200* success.
## View Details of a Team
`GET /api/v0/accounts/{name}/Teams/{teamname}`
Example Response:
```json
{
"id": 5,
"orgID": 4,
"type": "managed",
"name": "testers",
"description": "i have altered the description, pray that i do not alter it any further"
}
```
**Authorization**
Client must be authenticated as a member of the organization.
**Status Codes**
- *403* the client is not authorized.
- *404* no such team exists.
- *200* success.
## List a Team's Members
`GET /api/v0/accounts/{name}/teams/{teamname}/members`
Example Response:
```json
{
"members": [
{
"id": 8,
"type": "user",
"name": "midei",
"isActive": true
},
{
"id": 10,
"type": "user",
"name": "rajat",
"isActive": true
},
{
"id": 12,
"type": "user",
"name": "banjot",
"isActive": true
},
{
"id": 15,
"type": "user",
"name": "jon",
"isActive": true
}
]
}
```
**Authorization**
Client must be authenticated as a system admin, a member of the "owners" team
in the organization, or a member of the team in question.
**Status Codes**
- *403* the client is not authorized.
- *404* no such team exists.
- *200* success.
## Check if a User is a Member of a Team
`GET /api/v0/accounts/{name}/teams/{teamname}/members/{member}`
**Authorization**
Client must be authenticated as a user which has visibility into the team
(i.e., a member of the team or an owner of the organization).
**Status Codes**
- *403* the client is not authorized.
- *404* no such teams exists or user is not a member.
- *204* success (user is a member).
## Add a User to a Team (if not LDAP synced).
`PUT /api/v0/accounts/{name}/teams/{teamname}/members/{member}`
**Authorization**
Client must be authenticated as a system admin or a member of the "owners"
team in the organization.
**Status Codes**
- *403* the client is not authorized.
- *404* no such team exists.
- *200* success.
## Remove a User from a Team (if not LDAP synced).
`DELETE /api/v0/accounts/{name}/teams/{teamname}/members/{member}`
**Authorization**
Client must be authenticated as a system admin or a member of the "owners"
team in the organization.
**Status Codes**
- *403* the client is not authorized.
- *404* no such team exists.
- *200* success.
## Remove a Team.
`DELETE /api/v0/accounts/{name}/teams/{teamname}`
**Authorization**
Client must be authenticated as a system admin or a member of the "owners"
team in the organization.
**Status Codes**
- *403* the client is not authorized.
- *204* success.

146
api/dtr_1_3_user_repo_access.md Executable file
View File

@ -0,0 +1,146 @@
+++
title = "DTR User Repository API"
description = "Docker Trusted Registry 1.3 User-Owned Repository Acces"
keywords = ["API, Docker, index, REST, documentation, Docker Trusted Registry, registry"]
weight = 66
[menu.main]
parent = "smn_remoteapi"
+++
# Docker Trusted Registry 1.3 User-Owned Repository Access
User accounts can be granted `read-only`, `read-write`, or `admin` level access
to any repository that is owned by another user account.
**`read-only`**
- user can pull from the repository
**`read-write`**
- user can pull from the repository
- user can push to the repository
**`admin`**
- user can pull from the repository
- user can push to the repository
- user can manage other users' access to the repository
## List Users Granted Access to a User-Owned Repository
`GET /api/v0/repositories/{namespace}/{reponame}/userAccess`
Example Response:
```json
{
"repository": {
"id": 28,
"namespace": "josh",
"name": "public-app",
"shortDescription": "An Open-Source Retro Turboencabulator",
"longDescription": "For a number of years now, work has been proceeding in order to bring perfection to the crudely conceived idea of a transmission that would not only supply inverse reactive current for use in unilateral phase detractors, but would also be capable of automatically synchronizing cardinal grammeters. Such an instrument is the turbo-encabulator.\nNow basically the only new principle involved is that instead of power being generated by the relative motion of conductors and fluxes, it's produced by the modial interaction of magneto-reluctance and capacitive diractance.",
"visibility": "public",
"status": "ok"
},
"userAccessList": [
{
"accessLevel": "read-write",
"user": {
"id": 14,
"type": "user",
"name": "brian",
"isActive": true
}
},
{
"accessLevel": "read-write",
"user": {
"id": 6,
"type": "user",
"name": "don",
"isActive": true
}
}
]
}
```
**Authorization**
Client must be authenticated as a user which has 'admin' level access to the
repository.
**Status Codes**
- *404* the repository is not visible to the client.
- *400* the repository is not owned by a user.
- *403* the client is not authorized.
- *200* success.
## Set a User's Access to a User-Owned Repository
`PUT /api/v0/repositories/{namespace}/{reponame}/userAccess/{grantee}`
Example Request:
```http
PUT /api/v0/repositories/josh/public-app/userAccess/brian HTTP/1.1
Content-Type: application/json
{
"accessLevel": "read-write",
}
```
Example Response:
```json
{
"accessLevel": "read-write",
"user": {
"id": 14,
"type": "user",
"name": "brian",
"isActive": true
},
"repository": {
"id": 28,
"namespace": "josh",
"name": "public-app",
"shortDescription": "An Open-Source Retro Turboencabulator",
"longDescription": "For a number of years now, work has been proceeding in order to bring perfection to the crudely conceived idea of a transmission that would not only supply inverse reactive current for use in unilateral phase detractors, but would also be capable of automatically synchronizing cardinal grammeters. Such an instrument is the turbo-encabulator.\nNow basically the only new principle involved is that instead of power being generated by the relative motion of conductors and fluxes, it's produced by the modial interaction of magneto-reluctance and capacitive diractance.",
"visibility": "public",
"status": "ok"
}
}
```
**Authorization**
Client must be authenticated as a user which has 'admin' level access to the
repository.
**Status Codes**
- *404* the repository is not visible to the client.
- *400* repository is not owned by a user.
- *403* the client is unauthorized.
- *200* success.
## Revoke a User's Access to a User-Owned Repository
`DELETE /api/v0/repositories/{namespace}/{reponame}/userAccess/{grantee}`
**Authorization**
Client must be authenticated as a user which has 'admin' level access to the
repository.
**Status Codes**
- *404* the repository is not visible to the client.
- *400* the repository is not owned by a user.
- *403* the client is not authorized.
- *200* success.