[WIP] OSDOCS-20793: adds backend ref doc RHDH plugin API

_topic_maps/_topic_map.yml

@@ -102,6 +102,8 @@ Topics:
   File: rhcl-ocp-web-console
 - Name: Sharing and consuming APIs across teams
   File: rhcl-api-management
+- Name: Backstage backend API reference
+  File: backstage-backend-api-ref
 ---
 Name: Observability
 Dir: observe

develop/backstage-backend-api-ref.adoc

@@ -0,0 +1,12 @@
+:_mod-docs-content-type: ASSEMBLY
+include::_attributes/attributes.adoc[]
+[id="backstage-backend-api-ref"]
+= {rhdh} backend API reference
+:context: backstage-backend-api-ref
+
+toc::[]
+
+[role="_abstract"]
+When you need to understand the API surface that the {prodname} {rhdh} plugin uses, you can reference the REST API endpoints that the plugin backend exposes. All endpoints require authentication and enforce role-based access control (RBAC) permissions.
+
+include::modules/ref-backstage-backend-rest-api.adoc[leveloffset=+1]

modules/ref-backstage-backend-rest-api.adoc

@@ -0,0 +1,201 @@
+// Module included in the following assemblies:
+//
+// * develop/api-management-rest-api.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="ref-backstage-backend-rest-api_{context}"]
+= {rhdh} backend API reference
+
+[role="_abstract"]
+The {prodname} {rhdh} plugin backend exposes REST API endpoints at `/api/kuadrant/`. All endpoints require authentication and enforce role-based access control (RBAC) permissions. Use the following endpoint references to understand the API surface available for API management operations.
+
+[id="ref-backend-api-product-endpoints_{context}"]
+== API product endpoints
+
+Use the following endpoints to manage `APIProduct` resources. Non-administrator users see only `APIProduct` resources that they own.
+
+.API product endpoints
+[cols="1,3,3,2",options="header"]
+|===
+|Method |Endpoint |Description |Permission
+
+|`GET`
+|`/api/kuadrant/apiproducts`
+|Lists all API products. Non-administrators see only products that they own.
+|`kuadrant.apiproduct.list`
+
+|`GET`
+|`/api/kuadrant/apiproducts/_<namespace>_/_<name>_`
+|Returns a specific API product.
+|`kuadrant.apiproduct.read.own` or `kuadrant.apiproduct.read.all`
+
+|`POST`
+|`/api/kuadrant/apiproducts`
+|Creates a new API product.
+|`kuadrant.apiproduct.create`
+
+|`PATCH`
+|`/api/kuadrant/apiproducts/_<namespace>_/_<name>_`
+|Updates an existing API product.
+|`kuadrant.apiproduct.update.own` or `kuadrant.apiproduct.update.all`
+
+|`DELETE`
+|`/api/kuadrant/apiproducts/_<namespace>_/_<name>_`
+|Deletes an API product. This operation also deletes associated API keys.
+|`kuadrant.apiproduct.delete.own` or `kuadrant.apiproduct.delete.all`
+|===
+
+[id="ref-backend-http-route-endpoints_{context}"]
+== HTTPRoute endpoints
+
+Use the following endpoint to list `HTTPRoute` custom resources (CRs).
+
+.HTTPRoute endpoints
+[cols="1,3,3,2",options="header"]
+|===
+|Method |Endpoint |Description |Permission
+
+|`GET`
+|`/api/kuadrant/httproutes`
+|Lists all `HTTPRoute` resources.
+|`kuadrant.apiproduct.list`
+|===
+
+[id="ref-backend-plan-policy-endpoints_{context}"]
+== Plan policy endpoints
+
+Use the following endpoints to retrieve `PlanPolicy` custom resources (CRs).
+
+.Plan policy endpoints
+[cols="1,3,3,2",options="header"]
+|===
+|Method |Endpoint |Description |Permission
+
+|`GET`
+|`/api/kuadrant/planpolicies`
+|Lists all plan policies.
+|`kuadrant.planpolicy.list`
+
+|`GET`
+|`/api/kuadrant/planpolicies/_<namespace>_/_<name>_`
+|Returns a specific plan policy.
+|`kuadrant.planpolicy.read`
+|===
+
+[id="ref-backend-auth-policy-endpoints_{context}"]
+== AuthPolicy endpoints
+
+Use the following endpoint to list `AuthPolicy` custom resources (CRs).
+
+.AuthPolicy endpoints
+[cols="1,3,3,2",options="header"]
+|===
+|Method |Endpoint |Description |Permission
+
+|`GET`
+|`/api/kuadrant/authpolicies`
+|Lists all `AuthPolicy` resources.
+|`kuadrant.authpolicy.list`
+|===
+
+[id="ref-backend-rate-limit-policy-endpoints_{context}"]
+== RateLimitPolicy endpoints
+
+Use the following endpoint to list `RateLimitPolicy` custom resources (CRs).
+
+.RateLimitPolicy endpoints
+[cols="1,3,3,2",options="header"]
+|===
+|Method |Endpoint |Description |Permission
+
+|`GET`
+|`/api/kuadrant/ratelimitpolicies`
+|Lists all `RateLimitPolicy` resources.
+|`kuadrant.ratelimitpolicy.list`
+|===
+
+[id="ref-backend-api-key-endpoints_{context}"]
+== API key endpoints
+
+Use the following endpoints to manage API key requests and approvals.
+
+.API key endpoints
+[cols="1,3,3,2",options="header"]
+|===
+|Method |Endpoint |Description |Permission
+
+|`GET`
+|`/api/kuadrant/requests`
+|Lists API keys. Non-administrators see only keys that they own.
+|`kuadrant.apikey.read.own` or `kuadrant.apikey.read.all`
+
+|`GET`
+|`/api/kuadrant/requests/my`
+|Lists API keys for the current user.
+|`kuadrant.apikey.read.own`
+
+|`POST`
+|`/api/kuadrant/requests`
+|Creates an API key request.
+|`kuadrant.apikey.create`
+
+|`PATCH`
+|`/api/kuadrant/requests/_<namespace>_/_<name>_`
+|Edits a pending API key request.
+|`kuadrant.apikey.update.own` or `kuadrant.apikey.update.all`
+
+|`DELETE`
+|`/api/kuadrant/requests/_<namespace>_/_<name>_`
+|Deletes or cancels an API key request.
+|`kuadrant.apikey.delete.own` or `kuadrant.apikey.delete.all`
+
+|`POST`
+|`/api/kuadrant/requests/_<namespace>_/_<name>_/approve`
+|Approves an API key request.
+|`kuadrant.apikey.approve`
+
+|`POST`
+|`/api/kuadrant/requests/_<namespace>_/_<name>_/reject`
+|Rejects an API key request.
+|`kuadrant.apikey.approve`
+
+|`POST`
+|`/api/kuadrant/requests/bulk-approve`
+|Approves multiple API key requests.
+|`kuadrant.apikey.approve`
+
+|`POST`
+|`/api/kuadrant/requests/bulk-reject`
+|Rejects multiple API key requests.
+|`kuadrant.apikey.approve`
+|===
+
+[id="ref-rhcl-api-key-secret-endpoints_{context}"]
+== API key secret endpoints
+
+Use the following endpoint to retrieve API key secrets. The secret value is available for one-time retrieval only.
+
+.API key secret endpoints
+[cols="1,3,3,2",options="header"]
+|===
+|Method |Endpoint |Description |Permission
+
+|`GET`
+|`/api/kuadrant/apikeys/_<namespace>_/_<name>_/secret`
+|Returns the API key secret. This is a one-time read operation.
+|`kuadrant.apikey.read.own` or `kuadrant.apikey.read.all`
+|===
+
+[id="ref-backend-api-query-parameters_{context}"]
+== Query parameters
+
+You can use the following query parameters to filter API key request results.
+
+For `GET /api/kuadrant/requests`:
+
+`status`:: Filters results by status. Accepted values are `Pending`, `Approved`, and `Rejected`.
+`namespace`:: Filters results by Kubernetes namespace.
+
+For `GET /api/kuadrant/requests/my`:
+
+`namespace`:: Filters results by Kubernetes namespace.