Skip to content

Commit 4042ab9

Browse files
stevsmitSteven Smith
stevsmit
and
Steven Smith
authored
Adds using quay API docs (quay#1189)
Co-authored-by: Steven Smith <[email protected]>
1 parent fbef71d commit 4042ab9

File tree

7 files changed

+123
-8
lines changed

7 files changed

+123
-8
lines changed

‎api/master.adoc‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,11 +42,21 @@ include::modules/regenerating-robot-account-token-api.adoc[leveloffset=+2]
4242
include::modules/oci-referrers-oauth-access-token.adoc[leveloffset=+1]
4343
include::modules/creating-v2-oauth-access-token.adoc[leveloffset=+2]
4444
45+
//how to use the API
46+
include::modules/enabling-using-the-api.adoc[leveloffset=+1]
47+
include::modules/configuring-api-calls.adoc[leveloffset=+2]
48+
include::modules/using-the-api.adoc[leveloffset=+2]
49+
50+
4551
46-
//include::modules/proc_use-api.adoc[leveloffset=+1]
4752
4853
include::modules/creating-oauth-application-api.adoc[leveloffset=+1]
4954
55+
56+
57+
//include::modules/proc_use-api.adoc[leveloffset=+1]
58+
59+
5060
== {productname} Application Programming Interface (API)
5161
[id="ref-api-quay"]
5262

‎images/application-token.png‎

34.8 KB
Loading

‎modules/configuring-api-calls.adoc‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
[id="configuring-api-calls"]
2+
= Configuring {productname} to accept API calls
3+
4+
Prior to using the {productname} 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`.
5+
6+
.Procedure
7+
8+
. In your {productname} `config.yaml` file, set `BROWSER_API_CALLS_XHR_ONLY` to `false`. For example:
9+
+
10+
[source,yaml]
11+
----
12+
# ...
13+
BROWSER_API_CALLS_XHR_ONLY: false
14+
# ...
15+
----
16+
17+
. Restart your {productname} deployment.

‎modules/enabling-using-the-api.adoc‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
:_content-type: REFERENCE
2+
[id="enabling-using-the-api"]
3+
= Enabling and using the {productname} API
4+
5+
By leveraging the {productname} API, you can streamline container registry management, automate tasks, and integrate {productname}'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.
6+
7+
The following sections explain how to enable and use the {productname} API.

‎modules/proc_use-api.adoc‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -62,12 +62,6 @@ add the following line to the `config.yaml` on all nodes in the cluster and rest
6262
BROWSER_API_CALLS_XHR_ONLY: false
6363
```
6464

65-
== Accessing the {productname} API from the command line
66-
67-
You can use the `curl` command to GET, PUT, POST, or DELETE settings via the API
68-
for your {productname} cluster. Replace `<token>` with the OAuth access token you
69-
created earlier to get or change settings in the following examples.
70-
7165
////
7266
7367
=== Get superuser information

‎modules/reassigning-oauth-access-token.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
:_content-type: PROCEDURE
22
[id="reassigning-oauth-access-token"]
3-
== Reassigning an OAuth access token
3+
= Reassigning an OAuth access token
44

55
Organization administrators can assign OAuth API tokens to be created by other user's with specific permissions. This allows the audit logs to be reflected accurately when the token is used by a user that has no organization administrative permissions to create an OAuth API token.
66

‎modules/using-the-api.adoc‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
:_content-type: REFERENCE
2+
[id="using-the-api"]
3+
= Using the {productname} API
4+
5+
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 {productname} API command looks similar to the following example:
6+
7+
[source,terminal]
8+
----
9+
$ curl -X GET -H "Authorization: Bearer <your_access_token>" <1>
10+
https://<quay-server.example.com>/api/v1/<example>/<endpoint>/ <2>
11+
----
12+
<1> The OAuth 2 access token that was generated through the {productname} UI.
13+
<2> The URL of your {productname} deployment and the desired API endpoint.
14+
15+
All {productname} APIs are documented in the link:https://docs.redhat.com/en/documentation/red_hat_quay/{productname}/html-single/red_hat_quay_api_guide/index#red_hat_quay_application_programming_interface_api[{productname} 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:
16+
17+
[source,text]
18+
----
19+
*createAppToken* <1>
20+
Create a new app specific token for user. <2>
21+
22+
*POST /api/v1/user/apptoken* <3>
23+
24+
**Authorizations: **oauth2_implicit (**user:admin**) <4>
25+
26+
Request body schema (application/json)
27+
28+
*Path parameters* <5>
29+
30+
Name: **title**
31+
Description: Friendly name to help identify the token.
32+
Schema: string
33+
34+
*Responses* <6>
35+
36+
|HTTP Code|Description |Schema
37+
|201 |Successful creation |
38+
|400 |Bad Request |&lt;&lt;_apierror,ApiError&gt;&gt;
39+
|401 |Session required |&lt;&lt;_apierror,ApiError&gt;&gt;
40+
|403 |Unauthorized access |&lt;&lt;_apierror,ApiError&gt;&gt;
41+
|404 |Not found |&lt;&lt;_apierror,ApiError&gt;&gt;
42+
|===
43+
----
44+
<1> The name of the API endpoint.
45+
<2> A brief description of the API endpoint.
46+
<3> The API endpoint used for invocation.
47+
<4> The authorizations required to use the API endpoint.
48+
<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.
49+
<6> The API responses for this endpoint.
50+
51+
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.
52+
53+
.Prerequisites
54+
55+
* You have access to the {productname} API, which entails having already created an OAuth 2 access token.
56+
* You have set `BROWSER_API_CALLS_XHR_ONLY: false` in your `config.yaml` file.
57+
58+
.Procedure
59+
60+
* Create a user application by entering the link:https://docs.redhat.com/en/documentation/red_hat_quay/3.13/html-single/red_hat_quay_api_guide/index#appspecifictokens[`POST /api/v1/user/apptoken`] API call:
61+
+
62+
[source,terminal]
63+
----
64+
$ curl -X POST \
65+
-H "Authorization: Bearer <access_token>" <1>
66+
-H "Content-Type: application/json" \
67+
-d '{
68+
"title": "MyAppToken" <2>
69+
}' \
70+
"http://quay-server.example.com/api/v1/user/apptoken" <3>
71+
----
72+
<1> The Oauth access token.
73+
<2> The name of your application token.
74+
<3> The URL of your {productname} deployment appended with the `/api/v1/user/apptoken` endpoint.
75+
+
76+
.Example output
77+
+
78+
[source,terminal]
79+
----
80+
{"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"}}
81+
----
82+
83+
.Verification
84+
85+
. On the {productname} 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:
86+
+
87+
image::application-token.png[Application token]

0 commit comments

Comments
 (0)