Adds several API command examples (#1191)

Co-authored-by: Steven Smith <[email protected]>
quay · Jan 14, 2025 · 92ba17c · 92ba17c
1 parent 6d3bd1b
commit 92ba17c
Show file tree

Hide file tree

Showing 15 changed files with 242 additions and 7 deletions.
diff --git a/api/master.adoc b/api/master.adoc
@@ -49,10 +49,22 @@ include::modules/using-the-api.adoc[leveloffset=+2]
 include::modules/automating-quay-using-the-api.adoc[leveloffset=+2]
 
 
-
-include::modules/creating-oauth-application-api.adoc[leveloffset=+1]
-
-
+//API examples
+include::modules/quay-api-examples.adoc[leveloffset=+1]
+//application
+include::modules/creating-oauth-application-api.adoc[leveloffset=+2]
+//discovery
+include::modules/discovering-quay-api-endpoints.adoc[leveloffset=+2]
+//error
+include::modules/quay-error-details.adoc[leveloffset=+2]
+//global message
+include::modules/api-global-messages.adoc[leveloffset=+2]
+//viewing logs (aggregate)
+include::modules/viewing-usage-logs-api.adoc[leveloffset=+2]
+//exporting logs
+include::modules/use-quay-export-logs-api.adoc[leveloffset=+2]
+//manifest label
+include::modules/adding-managing-labels-api.adoc[leveloffset=+2]
 
 //include::modules/proc_use-api.adoc[leveloffset=+1]
 
@@ -64,7 +76,7 @@ This API allows you to perform many of the operations required to work with {pro
 
 include::modules/api-authorization.adoc[leveloffset=+2]
 
-
+//example procedures provided
 include::modules/api-appspecifictokens.adoc[leveloffset=+2]
 include::modules/api-appspecifictokens-createAppToken.adoc[leveloffset=+3]
 include::modules/api-appspecifictokens-listAppTokens.adoc[leveloffset=+3]
@@ -79,17 +91,21 @@ include::modules/api-build-cancelRepoBuild.adoc[leveloffset=+3]
 include::modules/api-build-requestRepoBuild.adoc[leveloffset=+3]
 include::modules/api-build-getRepoBuilds.adoc[leveloffset=+3]
 
+//example procedures provided
 include::modules/api-discovery.adoc[leveloffset=+2]
 include::modules/api-discovery-discovery.adoc[leveloffset=+3]
 
+//example procedures provided
 include::modules/api-error.adoc[leveloffset=+2]
 include::modules/api-error-getErrorDescription.adoc[leveloffset=+3]
 
+//example procedures provided
 include::modules/api-globalmessages.adoc[leveloffset=+2]
 include::modules/api-globalmessages-createGlobalMessage.adoc[leveloffset=+3]
 include::modules/api-globalmessages-getGlobalMessages.adoc[leveloffset=+3]
 include::modules/api-globalmessages-deleteGlobalMessage.adoc[leveloffset=+3]
 
+//example procedures provided
 include::modules/api-logs.adoc[leveloffset=+2]
 include::modules/api-logs-getAggregateUserLogs.adoc[leveloffset=+3]
 include::modules/api-logs-exportUserLogs.adoc[leveloffset=+3]
@@ -101,6 +117,7 @@ include::modules/api-logs-getAggregateRepoLogs.adoc[leveloffset=+3]
 include::modules/api-logs-exportRepoLogs.adoc[leveloffset=+3]
 include::modules/api-logs-listRepoLogs.adoc[leveloffset=+3]
 
+//example procedures provided
 include::modules/api-manifest.adoc[leveloffset=+2]
 include::modules/api-manifest-getManifestLabel.adoc[leveloffset=+3]
 include::modules/api-manifest-deleteManifestLabel.adoc[leveloffset=+3]

diff --git a/modules/api-appspecifictokens-createAppToken.adoc b/modules/api-appspecifictokens-createAppToken.adoc
@@ -36,3 +36,16 @@ _required_|Friendly name to help identify the token|string
 |403|Unauthorized access|&lt;&lt;_apierror,ApiError&gt;&gt;
 |404|Not found|&lt;&lt;_apierror,ApiError&gt;&gt;
 |===
+
+[discrete]
+== Example command
+[source,terminal]
+----
+ $ curl -X POST \
+  -H "Authorization: Bearer <access_token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "MyAppToken"
+  }' \
+  "http://quay-server.example.com/api/v1/user/apptoken"
+----
diff --git a/modules/api-appspecifictokens-getAppToken.adoc b/modules/api-appspecifictokens-getAppToken.adoc
@@ -33,3 +33,12 @@ _required_|The uuid of the app specific token|string
 |403|Unauthorized access|&lt;&lt;_apierror,ApiError&gt;&gt;
 |404|Not found|&lt;&lt;_apierror,ApiError&gt;&gt;
 |===
+
+[discrete]
+== Example command
+[source,terminal]
+----
+$ curl -X GET \
+  -H "Authorization: Bearer <access_token>" \
+  "http://quay-server.example.com/api/v1/user/apptoken/<token_uuid>"
+----
diff --git a/modules/api-appspecifictokens-listAppTokens.adoc b/modules/api-appspecifictokens-listAppTokens.adoc
@@ -34,3 +34,12 @@ _optional_|If true, only returns those tokens expiring soon|boolean
 |403|Unauthorized access|&lt;&lt;_apierror,ApiError&gt;&gt;
 |404|Not found|&lt;&lt;_apierror,ApiError&gt;&gt;
 |===
+
+[discrete]
+== Example command
+[source,terminal]
+----
+$ curl -X GET \
+  -H "Authorization: Bearer <access_token>" \
+  "http://quay-server.example.com/api/v1/user/apptoken"
+----
diff --git a/modules/api-appspecifictokens-revokeAppToken.adoc b/modules/api-appspecifictokens-revokeAppToken.adoc
@@ -33,3 +33,12 @@ _required_|The uuid of the app specific token|string
 |403|Unauthorized access|&lt;&lt;_apierror,ApiError&gt;&gt;
 |404|Not found|&lt;&lt;_apierror,ApiError&gt;&gt;
 |===
+
+[discrete]
+== Example command
+[source,terminal]
+----
+$ curl -X DELETE \
+  -H "Authorization: Bearer <access_token>" \
+  "http://quay-server.example.com/api/v1/user/apptoken/<token_uuid>"
+----
diff --git a/modules/api-discovery-discovery.adoc b/modules/api-discovery-discovery.adoc
@@ -32,3 +32,12 @@ _optional_|Whether to include internal APIs.|boolean
 |403|Unauthorized access|&lt;&lt;_apierror,ApiError&gt;&gt;
 |404|Not found|&lt;&lt;_apierror,ApiError&gt;&gt;
 |===
+
+[discrete]
+== Example command
+
+[source,terminal]
+----
+$ curl -X GET "https://<quay-server.example.com>/api/v1/discovery?query=true" \
+    -H "Authorization: Bearer <access_token>"
+----
diff --git a/modules/api-error-getErrorDescription.adoc b/modules/api-error-getErrorDescription.adoc
@@ -31,3 +31,12 @@ _required_|The error code identifying the type of error.|string
 |403|Unauthorized access|&lt;&lt;_apierror,ApiError&gt;&gt;
 |404|Not found|&lt;&lt;_apierror,ApiError&gt;&gt;
 |===
+
+[discrete]
+== Example command
+
+[source,terminal]
+----
+$ curl -X GET "https://<quay-server.example.com>/api/v1/error/<error_type>" \
+    -H "Authorization: Bearer <access_token>"
+----
diff --git a/modules/api-global-messages.adoc b/modules/api-global-messages.adoc
@@ -0,0 +1,55 @@
+:_content-type: PROCEDURE
+[id="api-global-messages"]
+= Global messages
+
+Global messages can be created, obtained, or deleted by using the {productname} API. 
+Use the following procedure to create, obtain, or delete a global message.
+
+.Prerequisites
+
+* You have created an OAuth 2 access token.
+
+.Procedure 
+
+. Create a message by using the link:https://docs.redhat.com/en/documentation/red_hat_quay/{producty}/html-single/red_hat_quay_api_guide/index#createglobalmessage[`POST /api/v1/message] endpoint:
++
+[source,terminal]
+----
+$ curl -X POST "https://quay-server.example.com/api/v1/messages" \
+    -H "Authorization: Bearer wplKtAuAX6DzAJwtB3X77nc18RFj2TKE5gTEk5K2" \
+    -H "Content-Type: application/json" \
+    -d '{
+        "message": {
+            "content": "Hi",
+            "media_type": "text/plain",
+            "severity": "info"
+        }
+    }'
+----
++
+This command does not return output.
+
+. Use the link:https://docs.redhat.com/en/documentation/red_hat_quay/{productname}/html-single/red_hat_quay_api_guide/index#getglobalmessages[`GET /api/v1/messages`] command to return the list of global messages:
++
+[source,terminal]
+----
+$ curl -X GET "https://<quay-server.example.com>/api/v1/messages" \
+    -H "Authorization: Bearer <access_token>"
+----
++
+.Example output
++
+[source,terminal]
+----
+{"messages": [{"uuid": "ecababd4-3451-4458-b5db-801684137444", "content": "Hi", "severity": "info", "media_type": "text/plain"}]}
+----
+
+. Delete the global message by using the link:https://docs.redhat.com/en/documentation/red_hat_quay/{productname}/html-single/red_hat_quay_api_guide/index#deleteglobalmessage[`DELETE /api/v1/message/{uuid}`] endpoint:
++
+[source,terminal]
+----
+$ curl -X DELETE "https://<quay-server.example.com>/api/v1/message/<uuid>" \
+    -H "Authorization: Bearer <access_token>"
+----
++
+This command does not return output.
diff --git a/modules/api-globalmessages-createGlobalMessage.adoc b/modules/api-globalmessages-createGlobalMessage.adoc
@@ -36,3 +36,19 @@ _required_|A single message|object
 |403|Unauthorized access|&lt;&lt;_apierror,ApiError&gt;&gt;
 |404|Not found|&lt;&lt;_apierror,ApiError&gt;&gt;
 |===
+
+[discrete]
+== Example command
+[source,terminal]
+----
+$ curl -X POST "https://quay-server.example.com/api/v1/messages" \
+    -H "Authorization: Bearer wplKtAuAX6DzAJwtB3X77nc18RFj2TKE5gTEk5K2" \
+    -H "Content-Type: application/json" \
+    -d '{
+        "message": {
+            "content": "Hi",
+            "media_type": "text/plain",
+            "severity": "info"
+        }
+    }'
+----
diff --git a/modules/api-globalmessages-deleteGlobalMessage.adoc b/modules/api-globalmessages-deleteGlobalMessage.adoc
@@ -33,3 +33,11 @@ _required_||string
 |403|Unauthorized access|&lt;&lt;_apierror,ApiError&gt;&gt;
 |404|Not found|&lt;&lt;_apierror,ApiError&gt;&gt;
 |===
+
+[discrete]
+== Example command
+[source,terminal]
+----
+$ curl -X DELETE "https://<quay-server.example.com>/api/v1/message/<uuid>" \
+    -H "Authorization: Bearer <access_token>"
+----
diff --git a/modules/api-globalmessages-getGlobalMessages.adoc b/modules/api-globalmessages-getGlobalMessages.adoc
@@ -21,3 +21,11 @@ Return a super users messages.
 |403|Unauthorized access|&lt;&lt;_apierror,ApiError&gt;&gt;
 |404|Not found|&lt;&lt;_apierror,ApiError&gt;&gt;
 |===
+
+[discrete]
+== Example command
+[source,terminal]
+----
+$ curl -X GET "https://<quay-server.example.com>/api/v1/messages" \
+    -H "Authorization: Bearer <access_token>"
+----
diff --git a/modules/creating-oauth-application-api.adoc b/modules/creating-oauth-application-api.adoc
@@ -13,7 +13,7 @@ Use the following procedure to create a user application token.
 
 .Prerequisites
 
-* You have access to the {productname} API, which entails having already created an OAuth 2 access token.
+* You have created an OAuth 2 access token.
 
 .Procedure
 
@@ -67,7 +67,7 @@ $ curl -X GET \
 {"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"}}
 ----
 
-* You can delete a user application token by entering the 
+* You can delete or revoke a user application token by using the link:https://docs.redhat.com/en/documentation/red_hat_quay/{producty}/html-single/red_hat_quay_api_guide/index#revokeapptoken[`DELETE /api/v1/user/apptoken/{token_uuid}`] endpoint:
 +
 [source,terminal]
 ----

diff --git a/modules/discovering-quay-api-endpoints.adoc b/modules/discovering-quay-api-endpoints.adoc
@@ -0,0 +1,30 @@
+:_content-type: PROCEDURE
+[id="discovering-quay-api-endpoints"]
+= Discovering {productname} API endpoints
+
+{productname} API endpoints are discoverable by using the API.
+
+Use the following procedure to discover available API endpoints.
+
+.Prerequisites
+
+* You have created an OAuth 2 access token.
+
+.Procedure
+
+* Enter the following link:https://docs.redhat.com/en/documentation/red_hat_quay/{producty}/html-single/red_hat_quay_api_guide/index#discovery_2[`GET /api/v1/discovery`] command to list all of the API endpoints available in the swagger API format:
++
+[source,terminal]
+----
+$ curl -X GET "https://<quay-server.example.com>/api/v1/discovery?query=true" \
+    -H "Authorization: Bearer <access_token>"
+----
++
+.Example output
++
+[source,terminal]
+----
+---
+: "Manage the tags of a repository."}, {"name": "team", "description": "Create, list and manage an organization's teams."}, {"name": "trigger", "description": "Create, list and manage build triggers."}, {"name": "user", "description": "Manage the current user."}, {"name": "userfiles", "description": ""}]}
+---
+----
diff --git a/modules/quay-api-examples.adoc b/modules/quay-api-examples.adoc
@@ -0,0 +1,5 @@
+:_content-type: CONCEPT
+[id="quay-api-examples"]
+= {productname} API examples
+
+The remainder of this chapter provides {productname} API examples for the features in which they are available. 
diff --git a/modules/quay-error-details.adoc b/modules/quay-error-details.adoc
@@ -0,0 +1,38 @@
+:_content-type: PROCEDURE
+[id="quay-error-details"]
+= Obtaining {productname} API error details
+
+{productname} API error details are discoverable by using the API.
+
+Use the following procedure to discover error details.
+
+.Prerequisites
+
+* You have created an OAuth 2 access token.
+
+.Procedure
+
+* You can obtain error details of the API by entering the link:https://docs.redhat.com/en/documentation/red_hat_quay/{producty}/html-single/red_hat_quay_api_guide/index#geterrordescription[`GET /api/v1/error/{error_type}`] endpoint. Note that you must include one of the following error codes:
++
+[options="header", width=100%, cols=".^2a,.^14a,.^4a"]
+|===
+|HTTP Code|Description|Schema
+|200|Successful invocation|&lt;&lt;_apierrordescription,ApiErrorDescription&gt;&gt;
+|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;
+|===
++
+[source,terminal]
+----
+$ curl -X GET "https://<quay-server.example.com>/api/v1/error/<error_type>" \
+    -H "Authorization: Bearer <access_token>"
+----
++
+.Example output
++
+[source,terminal]
+----
+curl: (7) Failed to connect to quay-server.example.com port 443 after 0 ms: Couldn't connect to server
+----