红帽全球峰会Red Hat Quay API Guide
Red Hat Quay API Guide
摘要
Preface
The Red Hat Quay application programming interface (API) is an OAuth 2 RESTful API that consists of a set of endpoints for adding, displaying, changing and deleting features for Red Hat Quay. This guide describes those endpoints and shows command and browser-based examples for accessing them.
第 1 章 Using the Red Hat Quay API
Red Hat Quay provides a full OAuth 2, RESTful API that:
- Is available from endpoints of each Red Hat Quay instance from the URL https://<yourquayhost>/api/v1
- Lets you connect to endpoints, via a browser, to get, delete, post, and put Red Hat Quay settings by enabling the Swagger UI
- Can be accessed by applications that make API calls and use OAuth tokens
- Sends and receives data as JSON
The following text describes how to access the Red Hat Quay API and use it to view and modify setting in your Red Hat Quay cluster. Appendix A lists and describes API endpoints.
1.1. Accessing the Quay API from Quay.io
If you don’t have your own Red Hat Quay cluster running yet, you can explore the Red Hat Quay API available from Quay.io from your web browser:
https://docs.quay.io/api/swagger/The API Explorer that appears shows Quay.io API endpoints. You will not see superuser API endpoints or endpoints for Red Hat Quay features that are not enabled on Quay.io (such as Repository Mirroring).
From API Explorer, you can get, and sometimes change, information on:
- Billing, subscriptions, and plans
- Repository builds and build triggers
- Error messages and global messages
- Repository images, manifests, permissions, notifications, vulnerabilities, and image signing
- Usage logs
- Organizations, members and OAuth applications
- User and robot accounts
- and more…
Select to open an endpoint to view the Model Schema for each part of the endpoint. Open an endpoint, enter any required parameters (such as a repository name or image), then select the Try it out! button to query or change settings associated with a Quay.io endpoint.
1.2. Create OAuth access token
To create an OAuth access token so you can access the API for your organization:
- Log in to Red Hat Quay and select your Organization (or create a new one).
- Select the Applications icon from the left navigation.
- Select Create New Application and give the new application a name when prompted.
- Select the new application.
- Select Generate Token from the left navigation.
- Select the checkboxes to set the scope of the token and select Generate Access Token.
- Review the permissions you are allowing and select Authorize Application to approve it.
- Copy the newly generated token to use to access the API.
1.3. Accessing your Quay API from a web browser
By enabling Swagger, you can access the API for your own Red Hat Quay instance through a web browser. This URL exposes the Red Hat Quay API explorer via the Swagger UI and this URL:
https://<yourquayhost>/api/v1/discovery.That way of accessing the API does not include superuser endpoints that are available on Red Hat Quay installations. Here is an example of accessing a Red Hat Quay API interface running on the local system by running the swagger-ui container image:
# export SERVER_HOSTNAME=<yourhostname>
# sudo podman run -p 8888:8080 -e API_URL=https://$SERVER_HOSTNAME:8443/api/v1/discovery docker.io/swaggerapi/swagger-uiWith the swagger-ui container running, open your web browser to localhost port 8888 to view API endpoints via the swagger-ui container.
To avoid errors in the log such as "API calls must be invoked with an X-Requested-With header if called from a browser," add the following line to the config.yaml on all nodes in the cluster and restart Red Hat Quay:
BROWSER_API_CALLS_XHR_ONLY: false
You can use the curl command to GET, PUT, POST, or DELETE settings via the API for your Red Hat Quay cluster. Replace <token> with the OAuth access token you created earlier to get or change settings in the following examples.
1.4.1. Get superuser information
$ curl -X GET -H "Authorization: Bearer <token_here>" \
"https://<yourquayhost>/api/v1/superuser/users/"For example:
$ curl -X GET -H "Authorization: Bearer mFCdgS7SAIoMcnTsHCGx23vcNsTgziAa4CmmHIsg" http://quay-server:8080/api/v1/superuser/users/ | jq
{
"users": [
{
"kind": "user",
"name": "quayadmin",
"username": "quayadmin",
"email": "quayadmin@example.com",
"verified": true,
"avatar": {
"name": "quayadmin",
"hash": "357a20e8c56e69d6f9734d23ef9517e8",
"color": "#5254a3",
"kind": "user"
},
"super_user": true,
"enabled": true
}
]
}1.4.2. Creating a superuser using the API
Configure a superuser name, as described in the Deploy Quay book:
- Use the configuration editor UI or
-
Edit the
config.yamlfile directly, with the option of using the configuration API to validate (and download) the updated configuration bundle
Create the user account for the superuser name:
Obtain an authorization token as detailed above, and use
curlto create the user:$ curl -H "Content-Type: application/json" -H "Authorization: Bearer Fava2kV9C92p1eXnMawBZx9vTqVnksvwNm0ckFKZ" -X POST --data '{ "username": "quaysuper", "email": "quaysuper@example.com" }' http://quay-server:8080/api/v1/superuser/users/ | jqThe returned content includes a generated password for the new user account:
{ "username": "quaysuper", "email": "quaysuper@example.com", "password": "EH67NB3Y6PTBED8H0HC6UVHGGGA3ODSE", "encrypted_password": "fn37AZAUQH0PTsU+vlO9lS0QxPW9A/boXL4ovZjIFtlUPrBz9i4j9UDOqMjuxQ/0HTfy38goKEpG8zYXVeQh3lOFzuOjSvKic2Vq7xdtQsU=" }
Now, when you request the list of users , it will show quaysuper as a superuser:
$ curl -X GET -H "Authorization: Bearer mFCdgS7SAIoMcnTsHCGx23vcNsTgziAa4CmmHIsg" http://quay-server:8080/api/v1/superuser/users/ | jq
{
"users": [
{
"kind": "user",
"name": "quayadmin",
"username": "quayadmin",
"email": "quayadmin@example.com",
"verified": true,
"avatar": {
"name": "quayadmin",
"hash": "357a20e8c56e69d6f9734d23ef9517e8",
"color": "#5254a3",
"kind": "user"
},
"super_user": true,
"enabled": true
},
{
"kind": "user",
"name": "quaysuper",
"username": "quaysuper",
"email": "quaysuper@example.com",
"verified": true,
"avatar": {
"name": "quaysuper",
"hash": "c0e0f155afcef68e58a42243b153df08",
"color": "#969696",
"kind": "user"
},
"super_user": true,
"enabled": true
}
]
}1.4.3. Directory synchronization
To enable directory synchronization for the team newteam in organization testadminorg, where the corresponding group name in LDAP is ldapgroup:
$ curl -X POST -H "Authorization: Bearer 9rJYBR3v3pXcj5XqIA2XX6Thkwk4gld4TCYLLWDF" \
-H "Content-type: application/json" \
-d '{"group_dn": "cn=ldapgroup,ou=Users"}' \
http://quay1-server:8080/api/v1/organization/testadminorg/team/newteam/syncingTo disable synchronization for the same team:
$ curl -X DELETE -H "Authorization: Bearer 9rJYBR3v3pXcj5XqIA2XX6Thkwk4gld4TCYLLWDF" \
http://quay1-server:8080/api/v1/organization/testadminorg/team/newteam/syncing1.4.4. Create a repository build via API
In order to build a repository from the specified input and tag the build with custom tags, users can use requestRepoBuild endpoint. It takes the following data:
{
"docker_tags": [
"string"
],
"pull_robot": "string",
"subdirectory": "string",
"archive_url": "string"
}
The archive_url parameter should point to a tar or zip archive that includes the Dockerfile and other required files for the build. The file_id parameter was apart of our older build system. It cannot be used anymore. If Dockerfile is in a sub-directory it needs to be specified as well.
The archive should be publicly accessible. OAuth app should have "Administer Organization" scope because only organization admins have access to the robots' account tokens. Otherwise, someone could get robot permissions by simply granting a build access to a robot (without having access themselves), and use it to grab the image contents. In case of errors, check the json block returned and ensure the archive location, pull robot, and other parameters are being passed correctly. Click "Download logs" on the top-right of the individual build’s page to check the logs for more verbose messaging.
1.4.5. Create an org robot
$ curl -X PUT https://quay.io/api/v1/organization/{orgname}/robots/{robot shortname} \
-H 'Authorization: Bearer <token>''1.4.6. Trigger a build
$ curl -X POST https://quay.io/api/v1/repository/YOURORGNAME/YOURREPONAME/build/ \
-H 'Authorization: Bearer <token>'Python with requests
import requests
r = requests.post('https://quay.io/api/v1/repository/example/example/image', headers={'content-type': 'application/json', 'Authorization': 'Bearer <redacted>'}, data={[<request-body-contents>})
print(r.text)1.4.7. Create a private repository
$ curl -X POST https://quay.io/api/v1/repository \
-H 'Authorization: Bearer {token}' \
-H 'Content-Type: application/json' \
-d '{"namespace":"yournamespace", "repository":"yourreponame",
"description":"descriptionofyourrepo", "visibility": "private"}' | jqThis API allows you to perform many of the operations required to work with Red Hat Quay repositories, users, and organizations.
2.2.1.1. Implementation Notes
Return the status for the builds specified by the build uuids.
2.2.1.2. Parameters
| Parameter | Value | Description | Parameter Type | Data Type |
| build_uuid | required | The UUID of the build | path | string |
| repository | required | The full path of the repository. e.g. namespace/name | path | string |
2.2.1.3. Response Messages
| HTTP Status Code | Reason | Response Model | Headers |
|---|---|---|---|
| 200 | Successful invocation |
| |
| 400 | Bad Request |
| |
| 401 | Session required |
| |
| 403 | Unauthorized access |
| |
| 404 | Not found |
|
2.2.2.1. Implementation Notes
Return the build logs for the build specified by the build uuid.
2.2.2.2. Parameters
| Parameter | Value | Description | Parameter Type | Data Type |
| build_uuid | required | The UUID of the build | path | string |
| repository | required | The full path of the repository. e.g. namespace/name | path | string |
2.2.2.3. Response Messages
| HTTP Status Code | Reason | Response Model | Headers |
|---|---|---|---|
| 200 | Successful invocation |
| |
| 400 | Bad Request |
| |
| 401 | Session required |
| |
| 403 | Unauthorized access |
| |
| 404 | Not found |
|
2.2.3.1. Implementation Notes
Returns information about a build.
2.2.3.2. Parameters
| Parameter | Value | Description | Parameter Type | Data Type |
| build_uuid | required | The UUID of the build | path | string |
| repository | required | The full path of the repository. e.g. namespace/name | path | string |
2.2.3.3. Response Messages
| HTTP Status Code | Reason | Response Model | Headers |
|---|---|---|---|
| 200 | Successful invocation |
| |
| 400 | Bad Request |
| |
| 401 | Session required |
| |
| 403 | Unauthorized access |
| |
| 404 | Not found |
|
2.2.4.1. Implementation Notes
Cancels a repository build.
2.2.4.2. Parameters
| Parameter | Value | Description | Parameter Type | Data Type |
| build_uuid | required | The UUID of the build | path | string |
| repository | required | The full path of the repository. e.g. namespace/name | path | string |
2.2.4.3. Response Messages
| HTTP Status Code | Reason | Response Model | Headers |
|---|---|---|---|
| 204 | Deleted |
| |
| 400 | Bad Request |
| |
| 401 | Session required |
| |
| 403 | Unauthorized access |
| |
| 404 | Not found |
|
2.2.5. get /api/v1/repository/{repository}/build/
2.2.5.1. Implementation Notes
Get the list of repository builds.
2.2.5.2. Parameters
| Parameter | Value | Description | Parameter Type | Data Type |
|---|---|---|---|---|
| repository | required | The full path of the repository. e.g. namespace/name | path | string |
| since | Returns all builds since the given unix timecode | query | integer | |
| limit | The maximum number of builds to return | query | integer |
2.2.5.3. Response Messages
| HTTP Status Code | Reason | Response Model | Headers |
|---|---|---|---|
| 200 | Successful invocation |
| |
| 400 | Bad Request |
| |
| 401 | Session required |
| |
| 403 | Unauthorized access |
| |
| 404 | Not found |
|
2.2.6. post /api/v1/repository/{repository}/build/
2.2.6.1. Implementation Notes
Request that a repository be built and pushed from the specified input.
2.2.6.2. Parameters
| Parameter | Value | Description | Parameter Type | Data Type |
|---|---|---|---|---|
| repository | required | The full path of the repository. e.g. namespace/name | path |
|
| body | required (Parameter content type: application/json) | Request body contents. | body |
|
2.2.6.3. Response Messages
| HTTP Status Code | Reason | Response Model | Headers |
|---|---|---|---|
| 201 | Successful creation |
| |
| 400 | Bad Request |
| |
| 401 | Session required |
| |
| 403 | Unauthorized access |
| |
| 404 | Not found |
|
2.3. discovery : API discovery information
2.4. error : Error details API
2.5. globalmessages : Messages API
2.6. image : List and lookup repository images
2.8. manifest : Manage the manifests of a repository
2.10. permission : Manage repository permissions
2.12. repository : List, create, and manage repositories
2.16. superuser : Superuser API
2.17. tag : Manage the tags of a repository
2.18.1.1. Implementation Notes
Returns the list of repository permissions for the org’s team.
2.18.1.2. Parameters
| Parameter | Value | Description | Parameter Type | Data Type |
| orgname | required | The name of the organization | path | string |
| teamname | required | The name of the team | path | string |
2.18.1.3. Response Messages
| HTTP Status Code | Reason | Response Model | Headers |
|---|---|---|---|
| 200 | Successful invocation |
| |
| 400 | Bad Request |
| |
| 401 | Session required |
| |
| 403 | Unauthorized access |
| |
| 404 | Not found |
|
2.18.2.1. Implementation Notes
Delete a member of a team. If the user is merely invited to join the team, then the invite is removed instead.
2.18.2.2. Parameters
| Parameter | Value | Description | Parameter Type | Data Type |
|---|---|---|---|---|
| orgname | required | The name of the organization | path | string |
| membername | required | The username of the team member | path | string |
| teamname | required | The name of the team | path | string |
2.18.2.3. Response Messages
| HTTP Status Code | Reason | Response Model | Headers |
|---|---|---|---|
| 204 | Deleted |
| |
| 400 | Bad Request |
| |
| 401 | Session required |
| |
| 403 | Unauthorized access |
| |
| 404 | Not found |
|
:leveloffset: +1
2.19.1. Implementation Notes
Retrieve the list of members for the specified team.
2.19.2. Parameters
| Parameter | Value | Description | Parameter Type | Data Type |
| orgname | required | The name of the organization | path | string |
| teamname | required | The name of the team | path | string |
| includePending | true / false | Whether to include pending members | query | boolean |
2.19.3. Response Messages
| HTTP Status Code | Reason | Response Model | Headers |
|---|---|---|---|
| 200 | Successful invocation |
| |
| 400 | Bad Request |
| |
| 401 | Session required |
| |
| 403 | Unauthorized access |
| |
| 404 | Not found |
|
2.20. trigger : Create, list and manage build triggers.
2.20.1.1. Implementation Notes
Activate the specified build trigger.
2.20.1.2. Parameters
| Parameter | Value | Description | Parameter Type | Data Type |
|---|---|---|---|---|
| trigger_uuid | required | The UUID of the build trigger | path |
|
| repository | required | The full path of the repository. e.g. namespace/name | path |
|
| body | required (Parameter content type: application/json) | Request body contents. | body |
|
2.20.1.3. Response Messages
| HTTP Status Code | Reason | Response Model | Headers |
|---|---|---|---|
| 201 | Successful creation |
| |
| 400 | Bad Request |
| |
| 401 | Session required |
| |
| 403 | Unauthorized access |
| |
| 404 | Not found |
|
2.20.2.1. Implementation Notes
List the builds started by the specified trigger.
2.20.2.2. Parameters
| Parameter | Value | Description | Parameter Type | Data Type |
|---|---|---|---|---|
| trigger_uuid | required | The UUID of the build trigger | path | string |
| repository | required | The full path of the repository. e.g. namespace/name | path | string |
| limit | The maximum number of builds to return | query | integer |
2.20.2.3. Response Messages
| HTTP Status Code | Reason | Response Model | Headers |
|---|---|---|---|
| 201 | Successful creation |
| |
| 400 | Bad Request |
| |
| 401 | Session required |
| |
| 403 | Unauthorized access |
| |
| 404 | Not found |
|
2.20.3.1. Implementation Notes
Manually start a build from the specified trigger.
2.20.3.2. Parameters
| Parameter | Value | Description | Parameter Type | Data Type |
|---|---|---|---|---|
| trigger_uuid | required | The UUID of the build trigger | path |
|
| repository | required | The full path of the repository. e.g. namespace/name | path |
|
| body | required (Parameter content type: application/json) | Request body contents. | body |
|
2.20.3.3. Response Messages
| HTTP Status Code | Reason | Response Model | Headers |
|---|---|---|---|
| 201 | Successful creation |
| |
| 400 | Bad Request |
| |
| 401 | Session required |
| |
| 403 | Unauthorized access |
| |
| 404 | Not found |
|
2.20.4.1. Implementation Notes
Get information for the specified build trigger.
2.20.4.2. Parameters
| Parameter | Value | Description | Parameter Type | Data Type |
|---|---|---|---|---|
| trigger_uuid | required | The UUID of the build trigger | path | string |
| repository | required | The full path of the repository. e.g. namespace/name | path | string |
2.20.4.3. Response Messages
| HTTP Status Code | Reason | Response Model | Headers |
|---|---|---|---|
| 200 | Successful invocation |
| |
| 400 | Bad Request |
| |
| 401 | Session required |
| |
| 403 | Unauthorized access |
| |
| 404 | Not found |
|
2.20.5.1. Implementation Notes
Updates the specified build trigger.
2.20.5.2. Parameters
| Parameter | Value | Description | Parameter Type | Data Type |
|---|---|---|---|---|
| trigger_uuid | required | The UUID of the build trigger | path |
|
| repository | required | The full path of the repository. e.g. namespace/name | path |
|
| body | required (Parameter content type: application/json) | Request body contents. | body |
|
2.20.5.3. Response Messages
| HTTP Status Code | Reason | Response Model | Headers |
|---|---|---|---|
| 200 | Successful invocation |
| |
| 400 | Bad Request |
| |
| 401 | Session required |
| |
| 403 | Unauthorized access |
| |
| 404 | Not found |
|
2.20.6.1. Implementation Notes
Delete the specified build trigger.
2.20.6.2. Parameters
| Parameter | Value | Description | Parameter Type | Data Type |
|---|---|---|---|---|
| trigger_uuid | required | The UUID of the build trigger | path | string |
| repository | required | The full path of the repository. e.g. namespace/name | path | string |
2.20.6.3. Response Messages
| HTTP Status Code | Reason | Response Model | Headers |
|---|---|---|---|
| 204 | Deleted |
| 400 |
| Bad Request | Mode: Model Schema { "status": 0, "error_message": "string", "title": "string", "error_type": "string", "detail": "string", "type": "string" |
| 401 |
| Session required | Model: Model Schema { "status": 0, "error_message": "string", "title": "string", "error_type": "string", "detail": "string", "type": "string" } |
| 403 |
| Unauthorized access | Model: Model Schema { "status": 0, "error_message": "string", "title": "string", "error_type": "string", "detail": "string", "type": "string" } |
| 404 |
2.20.7. get /api/v1/repository/{repository}/trigger/
2.20.7.1. Implementation Notes
List the triggers for the specified repository.
2.20.7.2. Parameters
| Parameter | Value | Description | Parameter Type | Data Type |
|---|---|---|---|---|
| repository | required | The full path of the repository e.g. namespace/name | path | string |
2.20.7.3. Response Messages
| HTTP Status Code | Reason | Response Model | Headers |
|---|---|---|---|
| 200 | Successful invocation |
| |
| 400 | Bad Request |
| |
| 401 | Session required |
| |
| 403 | Unauthorized access |
| |
| 404 | Not found |
|
2.21. user : Manage the current user.
2.21.1. get /api/v1/user/starred
2.21.1.1. Implementation Notes
List all starred repositories.
2.21.1.2. Parameters
| Parameter | Value | Description | Parameter Type | Data Type |
|---|---|---|---|---|
| next_page | required | The page token for the next page | path | string |
2.21.1.3. Response Messages
| HTTP Status Code | Reason | Response Model | Headers |
|---|---|---|---|
| 200 | Successful invocation |
| |
| 400 | Bad Request |
| |
| 401 | Session required |
| |
| 403 | Unauthorized access |
| |
| 404 | Not found |
|
2.21.2. post /api/v1/user/starred
2.21.2.1. Implementation Notes
2.21.2.2. Parameters
| Parameter | Value | Description | Parameter Type | Data Type |
|---|---|---|---|---|
| body | required (Parameter content type: application/json) | Request body contents. | body |
|
2.21.2.3. Response Messages
| HTTP Status Code | Reason | Response Model | Headers |
|---|---|---|---|
| 201 | Successful creation |
| |
| 400 | Bad Request |
| |
| 401 | Session required |
| |
| 403 | Unauthorized access |
| |
| 404 | Not found |
|
2.21.3. get /api/v1/user/
2.21.3.1. Implementation Notes
Get user information for the authenticated user.
2.21.3.2. Response Class (Status 200)
Model: Model Schema
{
"organizations": [
{}
],
"verified": true,
"avatar": {},
"anonymous": true,
"logins": [
{}
],
"can_create_repo": true,
"preferred_namespace": true,
"email": "string"
}Response Content Type: application/json
2.21.3.3. Response Messages
| HTTP Status Code | Reason | Response Model | Headers |
|---|---|---|---|
| 400 | Bad Request |
| |
| 401 | Session required |
| |
| 403 | Unauthorized access |
| |
| 404 | Not found |
|
2.21.4. delete /api/v1/user/starred/{repository}
2.21.4.1. Implementation Notes
Removes a star from a repository.
2.21.4.2. Parameters
| Parameter | Value | Description | Parameter Type | Data Type |
|---|---|---|---|---|
| repository | required | The full path of the repository. e.g. namespace/name | path | string |
2.21.4.3. Response Messages
| HTTP Status Code | Reason | Response Model | Headers |
|---|---|---|---|
| 204 | Deleted |
| |
| 400 | Bad Request |
| |
| 401 | Session required |
| |
| 403 | Unauthorized access |
| |
| 404 | Not found |
|
2.21.5. get /api/v1/users/{username}
2.21.5.1. Implementation Notes
Get user information for the specified user.
2.21.5.2. Parameters
| Parameter | Value | Description | Parameter Type | Data Type |
|---|---|---|---|---|
| username | required | path | string |
2.21.5.3. Response Messages
| HTTP Status Code | Reason | Response Model | Headers |
|---|---|---|---|
| 200 | Successful invocation |
| |
| 400 | Bad Request |
| |
| 401 | Session required |
| |
| 403 | Unauthorized access |
| |
| 404 | Not found |
|
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}