diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 7ea9e25dc24b..6ba1ce8bee07 100644 --- a/_topic_maps/_topic_map.yml +++ b/_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 diff --git a/develop/backstage-backend-api-ref.adoc b/develop/backstage-backend-api-ref.adoc new file mode 100644 index 000000000000..b89096f1ea53 --- /dev/null +++ b/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] diff --git a/modules/ref-backstage-backend-rest-api.adoc b/modules/ref-backstage-backend-rest-api.adoc new file mode 100644 index 000000000000..bf5cee80531f --- /dev/null +++ b/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/__/__` +|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/__/__` +|Updates an existing API product. +|`kuadrant.apiproduct.update.own` or `kuadrant.apiproduct.update.all` + +|`DELETE` +|`/api/kuadrant/apiproducts/__/__` +|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/__/__` +|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/__/__` +|Edits a pending API key request. +|`kuadrant.apikey.update.own` or `kuadrant.apikey.update.all` + +|`DELETE` +|`/api/kuadrant/requests/__/__` +|Deletes or cancels an API key request. +|`kuadrant.apikey.delete.own` or `kuadrant.apikey.delete.all` + +|`POST` +|`/api/kuadrant/requests/__/__/approve` +|Approves an API key request. +|`kuadrant.apikey.approve` + +|`POST` +|`/api/kuadrant/requests/__/__/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/__/__/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.