SupportConsoleDevelopersStart a trialContact

Chapter 5. Enabling and using the Red Hat Quay API

By leveraging the Red Hat Quay API, you can streamline container registry management, automate tasks, and integrate Red Hat Quay’s functionalities into your existing workflow. This can improve efficiency, offer enhanced flexibility (by way of repository management, user management, user permissions, image management, and so on), increase the stability of your organization, repository, or overall deployment, and more.

The following sections explain how to enable and use the Red Hat Quay API.

5.1. Configuring Red Hat Quay to accept API calls

Prior to using the Red Hat Quay API, you must disable BROWSER_API_CALLS_XHR_ONLY in your config.yaml file. This allows you to avoid such errors as API calls must be invoked with an X-Requested-With header if called from a browser.

Procedure

  1. In your Red Hat Quay config.yaml file, set BROWSER_API_CALLS_XHR_ONLY to false. For example: 

    # ...
BROWSER_API_CALLS_XHR_ONLY: false
# ...
  2. Restart your Red Hat Quay deployment.

5.2. Using the Red Hat Quay API

After you have created an application and generated an OAuth 2 access token with the desired settings, you can pass in the access token to GET, PUT, POST, or DELETE settings by using the API from the CLI. Generally, a Red Hat Quay API command looks similar to the following example: 

$ curl -X GET -H "Authorization: Bearer <your_access_token>" 1
    https://<quay-server.example.com>/api/v1/<example>/<endpoint>/ 2
1
The OAuth 2 access token that was generated through the Red Hat Quay UI.
2
The URL of your Red Hat Quay deployment and the desired API endpoint.

All Red Hat Quay APIs are documented in the link:https://docs.redhat.com/en/documentation/red_hat_quay/Red Hat Quay/html-single/red_hat_quay_api_guide/index#red_hat_quay_application_programming_interface_api[Red Hat Quay Application Programming Interface (API)] chapter. Understanding how they are documented is crucial to successful invocation. Take, for example, the following entry for the createAppToken API endpoint: 

*createAppToken* 1
Create a new app specific token for user. 2

*POST /api/v1/user/apptoken* 3

**Authorizations: **oauth2_implicit (**user:admin**) 4

 Request body schema (application/json)

*Path parameters* 5

Name: **title**
Description: Friendly name to help identify the token.
Schema: string

*Responses* 6

|HTTP Code|Description             |Schema
|201      |Successful creation     |
|400      |Bad Request             |&lt;&lt;_apierror,ApiError&gt;&gt;
|401      |Session required        |&lt;&lt;_apierror,ApiError&gt;&gt;
|403      |Unauthorized access     |&lt;&lt;_apierror,ApiError&gt;&gt;
|404      |Not found               |&lt;&lt;_apierror,ApiError&gt;&gt;
|===
1
The name of the API endpoint.
2
A brief description of the API endpoint.
3
The API endpoint used for invocation.
4
The authorizations required to use the API endpoint.
5
The available paths to be used with the API endpoint. In this example, title is the only path to be used with the POST /api/v1/user/apptoken endpoint.
6
The API responses for this endpoint.

In order to use an API endpoint, you pass in your access token and then include the appropriate fields depending on your needs. The following procedure shows you how to use the POST /api/v1/user/apptoken endpoint.

Prerequisites

  • You have access to the Red Hat Quay API, which entails having already created an OAuth 2 access token.
  • You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.

Procedure

  • Create a user application by entering the POST /api/v1/user/apptoken API call: 

    $ curl -X POST \
  -H "Authorization: Bearer <access_token>" 1
  -H "Content-Type: application/json" \
  -d '{
    "title": "MyAppToken" 2
  }' \
  "http://quay-server.example.com/api/v1/user/apptoken" 3
    1
    The Oauth access token.
    2
    The name of your application token.
    3
    The URL of your Red Hat Quay deployment appended with the /api/v1/user/apptoken endpoint.

    Example output

    {"token": {"uuid": "6b5aa827-cee5-4fbe-a434-4b7b8a245ca7", "title": "MyAppToken", "last_accessed": null, "created": "Wed, 08 Jan 2025 19:32:48 -0000", "expiration": null, "token_code": "K2YQB1YO0ABYV5OBUYOMF9MCUABN12Y608Q9RHFXBI8K7IE8TYCI4WEEXSVH1AXWKZCKGUVA57PSA8N48PWED9F27PXATFUVUD9QDNCE9GOT9Q8ACYPIN0HL"}}

Verification

  1. On the Red Hat Quay UI, click your username in the navigation pane Account Settings. The name of your application appears under the Docker CLI and other Application Tokens heading. For example:

    Application token

5.3. Automating Red Hat Quay processes by using the API

With the API, Red Hat Quay administrators and users with access to the API can automate repetitive tasks such as repository management or image pruning. The following example shows you how you might use a Python script and a cron job to to automate image pruning.

Prerequisites

  • You have access to the Red Hat Quay API, which entails having already created an OAuth 2 access token.
  • You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file.
  • You have installed the Python requests library using.
  • You have enabled cron jobs on your machine.

Procedure

  1. Create a Python script that executes an API command. The following example is used to prune images using the DELETE /api/v1/repository/{repository}/tag/{tag} API endpoint. 

    import requests 1

# Hard-coded values
API_BASE_URL = "http://<quay-server.example.com>/api/v1" 2
ACCESS_TOKEN = "<access_token>" 3
NAMESPACE = "<namespace_name>" 4
REPO_NAME = "<repository_name>" 5
TAG = "<tag_name>" 6

def delete_image_tag():
    # Construct the full API URL for deleting the tag
    url = f"{API_BASE_URL}/repository/{NAMESPACE}/{REPO_NAME}/tag/{TAG}"
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }

    # Send the DELETE request to the API
    response = requests.delete(url, headers=headers)

    # Check the response and print appropriate messages
    if response.status_code == 200:
        print("Tag deleted successfully")
    else:
        print("Failed to delete tag:", response.json())

# Execute the function
delete_image_tag()
    1
    Includes the import library in your Python code.
    2
    The URL of your registry appended with /api/v1.
    3
    Your OAuth 2 access token.
    4
    The namespace that holds the image tag.
    5
    The repository that holds the image tag.
    6
    The tag name of the image.
  2. Save the script as prune_images.py.

  3. Create a cron job that automatically runs the script:

    1. Open the crontab editor by running the following command: 

      $ crontab -e

    2. In the editor, add the cron job for running the script. The following example runs the script every minute: 

      * * * * * sudo python /path/to/prune_images.py >> /var/log/prune_images.log 2>&1
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.