From b01d1cbab3abc279faf544a7747bb50f81f9ec08 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Wed, 20 Aug 2025 09:40:02 -0500 Subject: [PATCH 01/20] Start outlining reference FF page Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/dev-portal/api-catalog-and-packaging.md | 50 +++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 app/dev-portal/api-catalog-and-packaging.md diff --git a/app/dev-portal/api-catalog-and-packaging.md b/app/dev-portal/api-catalog-and-packaging.md new file mode 100644 index 0000000000..4b959570d0 --- /dev/null +++ b/app/dev-portal/api-catalog-and-packaging.md @@ -0,0 +1,50 @@ +--- +title: Dev Portal API catalog and packaging +content_type: reference +layout: reference + +products: + - dev-portal + +breadcrumbs: + - /dev-portal/ +tags: + - api-catalog + - api-composition + +works_on: + - konnect +api_specs: + - konnect/api-builder +search_aliases: + - publish API specs + - API catalog + - API composition + - API packaging +description: | + placeholder +related_resources: + - text: replace me + url: / +faqs: + - q: placeholder + a: placeholder +--- + + + + +intro paragraph here + +## Steps + +### Create an API + +### Associate Gateway Service/CP + +### Assign Operations to Packages + +### Apply rate limits + +### Publish Packages to Portals From b0ea8b50618a5b30e5b9d2ccc02c851730df824f Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Thu, 21 Aug 2025 16:22:42 -0500 Subject: [PATCH 02/20] Continue draft Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/dev-portal/api-catalog-and-packaging.md | 114 +++++++++++++++++++- 1 file changed, 110 insertions(+), 4 deletions(-) diff --git a/app/dev-portal/api-catalog-and-packaging.md b/app/dev-portal/api-catalog-and-packaging.md index 4b959570d0..acf299e782 100644 --- a/app/dev-portal/api-catalog-and-packaging.md +++ b/app/dev-portal/api-catalog-and-packaging.md @@ -21,6 +21,7 @@ search_aliases: - API catalog - API composition - API packaging + - API bundle description: | placeholder related_resources: @@ -34,14 +35,119 @@ faqs: +You can compose different API packages from your APIs in Dev Portal. API packages allow you to: +* Flexibly add various operations and endpoints from your API to different packages depending on how you want to make those operations available in your Dev Portals +* Apply different rate limits on a per operation and per package basis +* Manage access control on a per package basis -intro paragraph here +The following table describes common API package use cases: + +{% table %} +columns: + - title: Use case + key: use-case + - title: Description + key: description + - title: Example + key: example +rows: + - use-case: Customize APIs for partners + description: Using API packages, you can customize which operations/endpoints are included in Dev Portals for partners. + example: If you have an API with two different endpoints, one for `/billing` and one for `/flights`, you can add just the `/flights` endpoint to an API package for partners and keep the `/billing` and `/flights` endpoints in a package that only the rest of your company can view. + - use-case: Manage APIs in development and production + description: As APIs move from development to a production environment, you can add them to the production API package so that users can view them in your Dev Portal. + example: Your API's `/billing` and `/flights` endpoints are both in development and included in the API package that is published to your internal Dev Portal. The `/flights` endpoint is released to production, so you can now create an API package that contains the `/flights` endpoint to release to your public, production Dev Portal. +{% endtable %} + -## Steps +## How API packages work -### Create an API +API packages are composed from operations. Operations allow you to compose REST-style APIs from a combination of the hostname, path, and method that are processed by the data plane. They are independent of Route definitions. If an OpenAPI spec is added to the API, the operations are autogenerated. -### Associate Gateway Service/CP +The following diagram shows an example of how API packages can be composed from operations: + + +{% mermaid %} +flowchart LR + subgraph subGraph0["Control plane"] + 1["Billing Gateway Service"] + 2["Flights Gateway Service"] + end + subgraph subGraph1["Partners API package"] + 3["POST /flights"] + 4["GET /flights"] + end + subgraph subGraph2["Org API package"] + 5["POST /billing"] + 6["GET /billing"] + 7["POST /flights"] + 8["GET /flights"] + end + 1 --> 5 & 6 + 2 --> 7 & 8 & 3 & 4 + style subGraph2 fill:#C8E6C9 + style subGraph1 fill:#BBDEFB +{% endmermaid %} + + +Packaging APIs involves the following steps: +1. Create an API and attach an OpenAPI spec. +1. Link a control plane (or control planes) for to allow developer consumption. +1. Apply the Access Control Enforcement (ACE) plugin globally. +1. Create an API package by adding operations and package rate limits. Operations are automatically mapped to Routes using your API's OpenAPI spec or you can create them manually. + +### ACE plugin + +Previously, when you created an API catalog in Dev Portal and linked the APIs to a Gateway Service, {{site.konnect_short_name}} would automatically apply the {{site.konnect_short_name}} application auth (KAA) plugin automatically. + +API packages uses the ACE plugin instead to manage developer access control to APIs. Unlike the KAA plugin, the ACE plugin can link to control planes to configure access control and create operations for Gateway Services in those control planes. + +### Package rate limits + +You can set individual rate limits on an API package as well as operations in that package. Keep the following in mind when configuring rate limits: +* API package rate limits apply across all operations in the API package **cumulatively**, not individually. +* Each Operation in an API Package can additionally have an individual rate limit defined. This rate limit applies simultaneously with the rate limiting being counted at the API Package level. +* ??? What happens when the Gateway Service or Route has rate limits applied? how do the two interact? + +For example, if you have the following rate limits set: +* **API package A**: 10 requests per second +* **Operation 1**: 5 requests per second + +A request that is authorized for Operation 1 will count toward both the rate limit for both the API Package A and Operation 1. + +So, if one request is sent, the authorized application will have nine requests remaining for API Package A and four requests remaining for Operation 1 for the configured time period (per second). + +### API package limitations + +When configuring API packages, keep the following limitations in mind: + +* If you have two endpoints in your spec, one with a trailing slash one without, both are counted as the same operation. +* If two operations have the same path and method, they are marked as the same operation. +* All operations for a control plane are removed when you unlinking the the control plane. +* Control planes can only be mapped to one API at a time. +* You can't change a version or edit a spec for an API if it would remove an operation. The recommended method to remove an operation is to unlink the control plane from the API. + +## Package APIs with Dev Portal + +This guide shows you how to create an API package in the {{site.konnect_short_name}} UI. + +### Prerequisites + +To package APIs with Dev Portal, you need: +* A v3 Dev Portal created in {{site.konnect_short_name}} +* The following roles: + * Editor role for APIs + * Publisher role for the API and API package +* [An API created](/dev-portal/apis/), ideally with an [OpenAPI spec](/dev-portal/apis/#api-specs) + +### Enable the ACE plugin for the control plane + +Enable the ACE plugin: + + +### Associate a control plane + +1. In {{site.konnect_short_name}}, ### Assign Operations to Packages From f3a4f86a19325aa538333cf5429935afd343583c Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Thu, 21 Aug 2025 18:24:53 -0500 Subject: [PATCH 03/20] Finish FF draft docs Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/dev-portal/api-catalog-and-packaging.md | 69 ++++++++++++++------- 1 file changed, 46 insertions(+), 23 deletions(-) diff --git a/app/dev-portal/api-catalog-and-packaging.md b/app/dev-portal/api-catalog-and-packaging.md index acf299e782..a21a766a1a 100644 --- a/app/dev-portal/api-catalog-and-packaging.md +++ b/app/dev-portal/api-catalog-and-packaging.md @@ -1,5 +1,5 @@ --- -title: Dev Portal API catalog and packaging +title: Dev Portal API packaging content_type: reference layout: reference @@ -23,13 +23,16 @@ search_aliases: - API packaging - API bundle description: | - placeholder + Learn how to package APIs in Dev Portal and what API packages are. related_resources: - - text: replace me - url: / -faqs: - - q: placeholder - a: placeholder + - text: Dev Portal APIs + url: /dev-portal/apis/ + - text: Automate your API catalog with Dev Portal + url: /how-to/automate-api-catalog/ + - text: Automate your API catalog with Terraform + url: /how-to/automate-api-catalog-with-terraform/ + - text: Application authentication strategies + url: /dev-portal/auth-strategies/ --- -You can compose different API packages from your APIs in Dev Portal. API packages allow you to: -* Flexibly add various operations and endpoints from your API to different packages depending on how you want to make those operations available in your Dev Portals -* Apply different rate limits on a per operation and per package basis -* Manage access control on a per package basis +Compose API packages from existing APIs in Dev Portal. API packages allow you to: +* Create distinct APIs for specific use cases or partners, based on existing API operations +* Link to multiple gateway services/routes for Developer self-service / Application Registration. +* Apply rate limiting policies to an API Package, or per operation +* Manage role-based access control to specific Developers/Teams The following table describes common API package use cases: @@ -56,16 +57,15 @@ columns: rows: - use-case: Customize APIs for partners description: Using API packages, you can customize which operations/endpoints are included in Dev Portals for partners. - example: If you have an API with two different endpoints, one for `/billing` and one for `/flights`, you can add just the `/flights` endpoint to an API package for partners and keep the `/billing` and `/flights` endpoints in a package that only the rest of your company can view. - - use-case: Manage APIs in development and production - description: As APIs move from development to a production environment, you can add them to the production API package so that users can view them in your Dev Portal. - example: Your API's `/billing` and `/flights` endpoints are both in development and included in the API package that is published to your internal Dev Portal. The `/flights` endpoint is released to production, so you can now create an API package that contains the `/flights` endpoint to release to your public, production Dev Portal. + example: If you have multiple APIs/services, you can select specific operations from each API, e.g. `GET /billing` and `GET /flights`, creating an API package for partners to an external Dev Portal, titled "Flight Billing API". Meanwhile Billing and Flights APIs can be published to your internal Dev Portal. + - use-case: Apply rate limits to Applications + description: While Gateway Services or Routes may have systemic rate limits in place, it's often necessary to get lower rate limits to Applications when exposing those capabilities to partners. When createing "Flight Billing API", `GET /billing` may need a lower rate limit of 10 request/minute, while the overall Package could have something higher like 5 requests/second. {% endtable %} ## How API packages work -API packages are composed from operations. Operations allow you to compose REST-style APIs from a combination of the hostname, path, and method that are processed by the data plane. They are independent of Route definitions. If an OpenAPI spec is added to the API, the operations are autogenerated. +API packages are composed from operations. Operations allow you to compose REST-style APIs from a combination of the hostname, path, and method that are processed by the control plane. They are used to map between the operations in your API and Gateway Routes. If an OpenAPI spec is added to the API, the operations are autogenerated. The following diagram shows an example of how API packages can be composed from operations: @@ -97,13 +97,13 @@ Packaging APIs involves the following steps: 1. Create an API and attach an OpenAPI spec. 1. Link a control plane (or control planes) for to allow developer consumption. 1. Apply the Access Control Enforcement (ACE) plugin globally. -1. Create an API package by adding operations and package rate limits. Operations are automatically mapped to Routes using your API's OpenAPI spec or you can create them manually. +1. Create an API package by adding operations and package rate limits. Operations are automatically mapped to Routes using your API's OpenAPI spec or you can create them manually. Gateway configuration is not directly modified, any unmatched operations will be highlighted to indicate action needed by the Gateway operator. ### ACE plugin Previously, when you created an API catalog in Dev Portal and linked the APIs to a Gateway Service, {{site.konnect_short_name}} would automatically apply the {{site.konnect_short_name}} application auth (KAA) plugin automatically. -API packages uses the ACE plugin instead to manage developer access control to APIs. Unlike the KAA plugin, the ACE plugin can link to control planes to configure access control and create operations for Gateway Services in those control planes. +API packages uses the ACE plugin instead to manage developer access control to APIs. Unlike the KAA plugin, the ACE plugin can link to Control Planes to configure access control and create operations for Gateway Services in those Control Planes. ### Package rate limits @@ -125,11 +125,11 @@ A request that is authorized for Operation 1 will count toward both the rate lim When configuring API packages, keep the following limitations in mind: -* If you have two endpoints in your spec, one with a trailing slash one without, both are counted as the same operation. -* If two operations have the same path and method, they are marked as the same operation. +* If you have two endpoints in your spec, one with a trailing slash one without, both are generated as the same operation. +* If two operations have the same path and method, they are generated as the same operation. * All operations for a control plane are removed when you unlink the control plane. * APIs can only be mapped to one control plane at a time. -* You can't change a version or edit a spec for an API if it would remove an operation. The recommended method to remove an operation is to unlink the control plane from the API. +* You can't change a version or edit a spec for an API if it would remove an operation, resulting in a breaking change. The recommended method to remove an operation is to unlink the control plane from the API. ## Package APIs with Dev Portal @@ -139,7 +139,7 @@ This guide shows you how to create an API package in the {{site.konnect_short_na To package APIs with Dev Portal, you need: * A v3 Dev Portal created in {{site.konnect_short_name}} -* A [Gateway Service](/gateway/entities/service/#set-up-a-gateway-service) and [Route](/gateway/entities/route/#set-up-a-route) added to your control plane +* A [Gateway Service](/gateway/entities/service/#set-up-a-gateway-service) and/or [Route](/gateway/entities/route/#set-up-a-route) added to your control plane * The following roles: * Editor role for APIs * Publisher role for the API and API package @@ -180,4 +180,4 @@ Your operations should now be autogenerated based on how your OpenAPI spec maps 1. Select an auth strategy from the **Authentication strategy** dropdown menu. 1. Click **Publish API**. -Your API package will now be published to your Dev Portal. API packages display the same as published APIs in the Dev Portal, and both allow developers to register applications with them. +Your API package will now be published to your Dev Portal. Published API Packages appear the same as Published APIs in the Dev Portal, and both allow developers to register applications with them. From 8e8e68ed43df648d4fafbd91c2d7c086a7a100d7 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Wed, 27 Aug 2025 11:37:54 -0500 Subject: [PATCH 08/20] Minor copy edit Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/dev-portal/api-catalog-and-packaging.md | 25 +++++++++++---------- 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/app/dev-portal/api-catalog-and-packaging.md b/app/dev-portal/api-catalog-and-packaging.md index 78dbeaa3fe..361ffebe0d 100644 --- a/app/dev-portal/api-catalog-and-packaging.md +++ b/app/dev-portal/api-catalog-and-packaging.md @@ -38,11 +38,11 @@ related_resources: -Compose API packages from existing APIs in Dev Portal. API packages allow you to: -* Create distinct APIs for specific use cases or partners, based on existing API operations -* Link to multiple gateway services/routes for Developer self-service / Application Registration. -* Apply rate limiting policies to an API Package, or per operation -* Manage role-based access control to specific Developers/Teams +You can compose API packages from existing APIs in Dev Portal. API packages allow you to: +* Create distinct APIs for specific use cases or partners based on existing API operations. +* Link to multiple Gateway Services and/or Routes for developer self-service and application registration. +* Apply rate limiting policies to an API Package, or per operation. +* Manage role-based access control to specific developers and teams. The following table describes common API package use cases: @@ -57,9 +57,10 @@ columns: rows: - use-case: Customize APIs for partners description: Using API packages, you can customize which operations/endpoints are included in Dev Portals for partners. - example: If you have multiple APIs/services, you can select specific operations from each API, e.g. `GET /billing` and `GET /flights`, creating an API package for partners to an external Dev Portal, titled "Flight Billing API". Meanwhile Billing and Flights APIs can be published to your internal Dev Portal. - - use-case: Apply rate limits to Applications - description: While Gateway Services or Routes may have systemic rate limits in place, it's often necessary to get lower rate limits to Applications when exposing those capabilities to partners. When createing "Flight Billing API", `GET /billing` may need a lower rate limit of 10 request/minute, while the overall Package could have something higher like 5 requests/second. + example: | + If you have multiple APIs/services, you can select specific operations from each API (for example, `GET /billing` and `GET /flights`) creating an API package for partners in an external Dev Portal, called "Flight Billing API". Meanwhile, Billing and Flights APIs can also be published to your internal Dev Portal. + - use-case: Apply rate limits to applications + description: While Gateway Services or Routes may have systemic rate limits in place, it's often necessary to apply lower rate limits to applications when exposing those capabilities to partners. When creating the "Flight Billing API" package, `GET /billing` may need a lower rate limit of 10 request per minute, while the overall API package could have something higher, like five requests per second. {% endtable %} @@ -97,13 +98,13 @@ Packaging APIs involves the following steps: 1. Create an API and attach an OpenAPI spec. 1. Link a control plane (or control planes) for to allow developer consumption. 1. Apply the Access Control Enforcement (ACE) plugin globally. -1. Create an API package by adding operations and package rate limits. Operations are automatically mapped to Routes using your API's OpenAPI spec or you can create them manually. Gateway configuration is not directly modified, any unmatched operations will be highlighted to indicate action needed by the Gateway operator. +1. Create an API package by adding operations and package rate limits. Operations are automatically mapped to Routes using your API's OpenAPI spec or you can create them manually. The Gateway configuration isn't directly modified– any unmatched operations will be highlighted to indicate that a user Gateway Manager permissions needs to perform an action. ### ACE plugin Previously, when you created an API catalog in Dev Portal and linked the APIs to a Gateway Service, {{site.konnect_short_name}} would automatically apply the {{site.konnect_short_name}} application auth (KAA) plugin automatically. -API packages uses the ACE plugin instead to manage developer access control to APIs. Unlike the KAA plugin, the ACE plugin can link to Control Planes to configure access control and create operations for Gateway Services in those Control Planes. +API packages uses the ACE plugin instead to manage developer access control to APIs. Unlike the KAA plugin, the ACE plugin can link to control planes to configure access control and create operations for Gateway Services in those control planes. ### Package rate limits @@ -129,7 +130,7 @@ When configuring API packages, keep the following limitations in mind: * If two operations have the same path and method, they are generated as the same operation. * All operations for a control plane are removed when you unlink the control plane. * APIs can only be mapped to one control plane at a time. -* You can't change a version or edit a spec for an API if it would remove an operation, resulting in a breaking change. The recommended method to remove an operation is to unlink the control plane from the API. +* You can't change a version or edit a spec for an API if it would remove an operation because this would result in a breaking change. The recommended method to remove an operation is to unlink the control plane from the API. ## Package APIs with Dev Portal @@ -180,4 +181,4 @@ Your operations should now be autogenerated based on how your OpenAPI spec maps 1. Select an auth strategy from the **Authentication strategy** dropdown menu. 1. Click **Publish API**. -Your API package will now be published to your Dev Portal. Published API Packages appear the same as Published APIs in the Dev Portal, and both allow developers to register applications with them. +Your API package will now be published to your Dev Portal. Published API packages appear the same as published APIs in the Dev Portal, and both allow developers to register applications with them. From dc73a0e4db24e51f0c02bc962397c1eca9070510 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Wed, 27 Aug 2025 11:40:22 -0500 Subject: [PATCH 09/20] Apply recommendation about spec to Gateway route mapping Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/dev-portal/api-catalog-and-packaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/dev-portal/api-catalog-and-packaging.md b/app/dev-portal/api-catalog-and-packaging.md index 361ffebe0d..441c1cf9e1 100644 --- a/app/dev-portal/api-catalog-and-packaging.md +++ b/app/dev-portal/api-catalog-and-packaging.md @@ -95,7 +95,7 @@ flowchart LR Packaging APIs involves the following steps: -1. Create an API and attach an OpenAPI spec. +1. Create an API and attach an OpenAPI spec. Operations from your API's OpenAPI spec should overlap with Routes to ensure requests will be routed to the correct Service. Gateway routing configuration is not directly modified by adding operations. 1. Link a control plane (or control planes) for to allow developer consumption. 1. Apply the Access Control Enforcement (ACE) plugin globally. 1. Create an API package by adding operations and package rate limits. Operations are automatically mapped to Routes using your API's OpenAPI spec or you can create them manually. The Gateway configuration isn't directly modified– any unmatched operations will be highlighted to indicate that a user Gateway Manager permissions needs to perform an action. From 6e021189cd0eca0eea898636484fed4afbbbbbcf Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Wed, 27 Aug 2025 11:43:42 -0500 Subject: [PATCH 10/20] Fix the table formatting Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/dev-portal/api-catalog-and-packaging.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/app/dev-portal/api-catalog-and-packaging.md b/app/dev-portal/api-catalog-and-packaging.md index 441c1cf9e1..c4f893459e 100644 --- a/app/dev-portal/api-catalog-and-packaging.md +++ b/app/dev-portal/api-catalog-and-packaging.md @@ -60,7 +60,9 @@ rows: example: | If you have multiple APIs/services, you can select specific operations from each API (for example, `GET /billing` and `GET /flights`) creating an API package for partners in an external Dev Portal, called "Flight Billing API". Meanwhile, Billing and Flights APIs can also be published to your internal Dev Portal. - use-case: Apply rate limits to applications - description: While Gateway Services or Routes may have systemic rate limits in place, it's often necessary to apply lower rate limits to applications when exposing those capabilities to partners. When creating the "Flight Billing API" package, `GET /billing` may need a lower rate limit of 10 request per minute, while the overall API package could have something higher, like five requests per second. + description: While Gateway Services or Routes may have systemic rate limits in place, it's often necessary to apply lower rate limits to applications when exposing those capabilities to partners. + example: | + When creating the "Flight Billing API" package, `GET /billing` may need a lower rate limit of 10 request per minute, while the overall API package could have something higher, like five requests per second. {% endtable %} From a76a81b520c14aa70c81fe7dfac894aef5352e89 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Fri, 12 Sep 2025 14:33:06 -0500 Subject: [PATCH 11/20] Fix tags, add ACE plugin config content, other feedback fixes Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/_data/schemas/frontmatter/tags.json | 1 + app/dev-portal/api-catalog-and-packaging.md | 42 +++++++++++++++++++++ 2 files changed, 43 insertions(+) diff --git a/app/_data/schemas/frontmatter/tags.json b/app/_data/schemas/frontmatter/tags.json index 24d0aab346..9829afd5e3 100644 --- a/app/_data/schemas/frontmatter/tags.json +++ b/app/_data/schemas/frontmatter/tags.json @@ -12,6 +12,7 @@ "analytics", "anthropic", "api-catalog", + "api-composition", "api-products", "apiops", "application-registration", diff --git a/app/dev-portal/api-catalog-and-packaging.md b/app/dev-portal/api-catalog-and-packaging.md index c4f893459e..7c40ad3bde 100644 --- a/app/dev-portal/api-catalog-and-packaging.md +++ b/app/dev-portal/api-catalog-and-packaging.md @@ -108,6 +108,47 @@ Previously, when you created an API catalog in Dev Portal and linked the APIs to API packages uses the ACE plugin instead to manage developer access control to APIs. Unlike the KAA plugin, the ACE plugin can link to control planes to configure access control and create operations for Gateway Services in those control planes. +The ACE plugin runs *after* all other [authentication plugins](/plugins/?category=authentication) run. For example, if you have Key Authentication configured and it rejects a request, the ACE plugin *will not* run. If you're using the `config.anonymous` ACE plugin configuration, the [plugin priority](/gateway/entities/plugin/#plugin-priority) needs to be set in such a way that it executes after all other authentication plugins. For example, you can set a provisional priority of 949 so the plugin runs after KAA (which has a priority of 950). + + +#### Route matching policy + +When you configure the ACE plugin, you must set either `required` or `present` for `config.match_policy`. This determines how the ACE plugin will behave when a request doesn't match an existing Route. + +The following table describes what the `match_policy` values do and when to use each: +{% table %} +columns: + - title: Setting + key: setting + - title: Description + key: description + - title: Limitations + key: limitations + - title: Use cases + key: use-case +rows: + - setting: | + `required` + description: | + Requires every incoming request to match a defined operation from an API or API package in Dev Portal. If a request doesn't match, ACE rejects the request outright with a 401. All traffic will be rejected except operations or Routes in published APIs linked to an ACE-enabled {{site.base_gateway}}. + limitations: | + * Misconfigurations can overexpose unintended Routes. + * Shuts down all traffic outside of published Dev Portal APIs. + * If the plugin is improperly configured, potentially all traffic could be terminated. + use-case: | + * You want to lock down {{site.konnect_short_name}} so that only traffic that is part of an explicitly defined API operation is allowed through. + * You only plan to provide self-service access via your Dev Portal. + - setting: | + `if_present` + description: | + The ACE plugin only engages with a request when it matches an operation. If a request doesn't match, ACE lets the request pass through untouched. This means that non-matching requests aren't rejected, but ACE also won't perform authentication and authorization on them. This allows a request to still be processed by other plugins with a [lower priority](/gateway/entities/plugin/#plugin-priority) than ACE. + limitations: | + All traffic outside of published APIs linked to an ACE-enabled {{site.base_gateway}} won't be access controlled, this must be configured with a different plugin. Dev Portal will not be able to protect all operations. + use-case: | + * You have an environment where some Gateway Services or Routes are governed by Dev Portal–exposed APIs (with ACE), while others are regular Routes that should be left alone. + * You already have existing traffic and other access controls in place and want to avoid interruption. +{% endtable %} + ### Package rate limits You can set individual rate limits on an API package as well as operations in that package. Keep the following in mind when configuring rate limits: @@ -117,6 +158,7 @@ You can set individual rate limits on an API package as well as operations in th * Requests that are under the current limit for the Service and API Package will be counted towards both. * Requests that surpass the rate limit of an API package won't be counted towards rate limits applied from other rate limiting plugins. * Requests that surpass the rate limit of other rate limiting plugins are still counted towards the rate limits applied for API packages. This is because the ACE plugin runs before other rate limiting plugins under the default plugin priorities. You can adjust this behavior with [custom plugin priority values](/gateway/entities/plugin/#dynamic-plugin-ordering). + * Rate limiting is applied per credential. For example, if you have the following rate limits set: * **API package A**: 10 requests per second From 2c176e5873388826bec716d35b2d453cebcffcd1 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Wed, 17 Sep 2025 15:30:26 -0500 Subject: [PATCH 12/20] Apply more feedback Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/dev-portal/api-catalog-and-packaging.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/app/dev-portal/api-catalog-and-packaging.md b/app/dev-portal/api-catalog-and-packaging.md index 7c40ad3bde..d2fefc6fcf 100644 --- a/app/dev-portal/api-catalog-and-packaging.md +++ b/app/dev-portal/api-catalog-and-packaging.md @@ -97,7 +97,7 @@ flowchart LR Packaging APIs involves the following steps: -1. Create an API and attach an OpenAPI spec. Operations from your API's OpenAPI spec should overlap with Routes to ensure requests will be routed to the correct Service. Gateway routing configuration is not directly modified by adding operations. +1. Create an API and attach an OpenAPI spec. Operations from your API's OpenAPI spec should overlap with Routes to ensure requests will be routed to the correct Service. Gateway routing configuration isn't directly modified by adding operations. 1. Link a control plane (or control planes) for to allow developer consumption. 1. Apply the Access Control Enforcement (ACE) plugin globally. 1. Create an API package by adding operations and package rate limits. Operations are automatically mapped to Routes using your API's OpenAPI spec or you can create them manually. The Gateway configuration isn't directly modified– any unmatched operations will be highlighted to indicate that a user Gateway Manager permissions needs to perform an action. @@ -130,7 +130,10 @@ rows: - setting: | `required` description: | - Requires every incoming request to match a defined operation from an API or API package in Dev Portal. If a request doesn't match, ACE rejects the request outright with a 401. All traffic will be rejected except operations or Routes in published APIs linked to an ACE-enabled {{site.base_gateway}}. + Requires every incoming request to match a defined operation from an API or API package in Dev Portal. If a request doesn't match, ACE rejects the request outright with a 404. All traffic will be rejected except operations or Routes in published APIs linked to an ACE-enabled {{site.base_gateway}}. + + {:.danger} + > **Warning:** Setting the `match_policy` to `required` can **block all traffic with a 404**. Any undefined endpoints will be blocked. If you accidentally enable this in your control planes, this could cause a potential outage in production. limitations: | * Misconfigurations can overexpose unintended Routes. * Shuts down all traffic outside of published Dev Portal APIs. @@ -153,7 +156,7 @@ rows: You can set individual rate limits on an API package as well as operations in that package. Keep the following in mind when configuring rate limits: * API package rate limits apply across all operations in the API package **cumulatively**, not individually. -* Each Operation in an API Package can additionally have an individual rate limit defined. This rate limit applies simultaneously with the rate limiting being counted at the API Package level. +* Each Operation in an API Package can additionally have an individual rate limit defined. When an operation-level override is present, the package-level limit is ignored for that operation. * API package rate limits are applied simultaneously with rate limits from other plugins on gateway entities: * Requests that are under the current limit for the Service and API Package will be counted towards both. * Requests that surpass the rate limit of an API package won't be counted towards rate limits applied from other rate limiting plugins. @@ -164,7 +167,7 @@ For example, if you have the following rate limits set: * **API package A**: 10 requests per second * **Operation 1**: 5 requests per second -A request that is authorized for Operation 1 will count toward both the rate limit for both the API Package A and Operation 1. So, if one request is sent, the authorized application will have nine requests remaining for API Package A and four requests remaining for Operation 1 for the configured time period (per second). +Because an operation-level override is present, the package-level limit is ignored for that operation. This means a request authorized for Operation 1 will only count toward its specific operation-level limit. So, if one request is sent, the authorized application will have four requests remaining for Operation 1 for the configured time period (per second). The package-level limit of API Package A doesn't apply to this request. ### API package limitations From a97ff24f766c65bc0405df4126dce18d19919c40 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Tue, 14 Oct 2025 09:39:31 -0500 Subject: [PATCH 13/20] Apply suggestions from code review --- app/dev-portal/api-catalog-and-packaging.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/app/dev-portal/api-catalog-and-packaging.md b/app/dev-portal/api-catalog-and-packaging.md index d2fefc6fcf..bf3a2e9a26 100644 --- a/app/dev-portal/api-catalog-and-packaging.md +++ b/app/dev-portal/api-catalog-and-packaging.md @@ -98,7 +98,7 @@ flowchart LR Packaging APIs involves the following steps: 1. Create an API and attach an OpenAPI spec. Operations from your API's OpenAPI spec should overlap with Routes to ensure requests will be routed to the correct Service. Gateway routing configuration isn't directly modified by adding operations. -1. Link a control plane (or control planes) for to allow developer consumption. +1. Link a control plane to allow developer consumption. 1. Apply the Access Control Enforcement (ACE) plugin globally. 1. Create an API package by adding operations and package rate limits. Operations are automatically mapped to Routes using your API's OpenAPI spec or you can create them manually. The Gateway configuration isn't directly modified– any unmatched operations will be highlighted to indicate that a user Gateway Manager permissions needs to perform an action. @@ -187,7 +187,7 @@ This guide shows you how to create an API package in the {{site.konnect_short_na To package APIs with Dev Portal, you need: * A v3 Dev Portal created in {{site.konnect_short_name}} -* A [Gateway Service](/gateway/entities/service/#set-up-a-gateway-service) and/or [Route](/gateway/entities/route/#set-up-a-route) added to your control plane +* A [Gateway Service](/gateway/entities/service/#set-up-a-gateway-service) and/or [Route](/gateway/entities/route/#set-up-a-route) added to your control plane ({{site.base_gateway}} 3.12 or later) * The following roles: * Editor role for APIs * Publisher role for the API and API package From 94d6d32660b5ef70d047fe733ebc3095942b357e Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Thu, 15 Jan 2026 16:12:45 -0600 Subject: [PATCH 14/20] Make ace stuff includes, update steps, change file name and redirects Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/_includes/plugins/ace/ace-overview.md | 5 ++ .../plugins/ace/ace-route-matching.md | 40 +++++++++ app/_kong_plugins/ace/index.md | 47 +---------- app/_redirects | 1 + ...alog-and-packaging.md => api-packaging.md} | 82 ++++++------------- 5 files changed, 74 insertions(+), 101 deletions(-) create mode 100644 app/_includes/plugins/ace/ace-overview.md create mode 100644 app/_includes/plugins/ace/ace-route-matching.md rename app/dev-portal/{api-catalog-and-packaging.md => api-packaging.md} (65%) diff --git a/app/_includes/plugins/ace/ace-overview.md b/app/_includes/plugins/ace/ace-overview.md new file mode 100644 index 0000000000..6cf5ac7556 --- /dev/null +++ b/app/_includes/plugins/ace/ace-overview.md @@ -0,0 +1,5 @@ +The Access Control Enforcement (ACE) plugin manages developer access control to APIs published with Dev Portal. + +Previously, when you created an API catalog in Dev Portal and linked the APIs to a Gateway Service, {{site.konnect_short_name}} would automatically apply the {{site.konnect_short_name}} application auth (KAA) plugin automatically. API packages uses the ACE plugin instead to manage developer access control to APIs. Unlike the KAA plugin, the ACE plugin can link to control planes to configure access control and create operations for Gateway Services in those control planes. + +The ACE plugin runs *after* all other [authentication plugins](/plugins/?category=authentication) run. For example, if you have [Key Authentication](/plugins/key-auth/) configured and it rejects a request, the ACE plugin *will not* run. To allow for multiple authentication plugins, each must set the [`config.anonymous`](/plugins/ace/reference/#schema--config-anonymous) plugin configuration. Additionally, the choice to allow or reject an `anonymous` result after all authentication plugins have run needs to be controlled as described in [using multiple authentication methods](/gateway/authentication/#using-multiple-authentication-methods). \ No newline at end of file diff --git a/app/_includes/plugins/ace/ace-route-matching.md b/app/_includes/plugins/ace/ace-route-matching.md new file mode 100644 index 0000000000..54273adbd0 --- /dev/null +++ b/app/_includes/plugins/ace/ace-route-matching.md @@ -0,0 +1,40 @@ +When you configure the ACE plugin, you must set either `required` or `present` for [`config.match_policy`](/plugins/ace/reference/#schema--config-match-policy). This determines how the ACE plugin will behave when a request doesn't match an existing Route. + +Keep in mind that misconfigurations can overexpose unintended Routes. + +The following table describes what the `match_policy` values do and when to use each: +{% table %} +columns: + - title: Setting + key: setting + - title: Description + key: description + - title: Limitations + key: limitations + - title: Use cases + key: use-case +rows: + - setting: | + `required` + description: | + Requires every incoming request to match a defined operation from an API or API package in Dev Portal. If a request doesn't match, ACE rejects the request outright with a 404. All traffic will be rejected except operations or Routes in published APIs linked to an ACE-enabled {{site.base_gateway}}. + + {:.danger} + > **Warning:** Setting the [`match_policy`](/plugins/ace/reference/#schema--config-match-policy) to `required` can **block all traffic with a 404**. Any undefined endpoints will be blocked. If you accidentally enable this in your control planes, this could cause a potential outage in production. + limitations: | + * Shuts down all traffic outside of ACE-enabled Dev Portal APIs. + * If the plugin is improperly configured, potentially all traffic could be terminated. + use-case: | + * You want to lock down {{site.konnect_short_name}} so that only traffic that is part of an explicitly defined API operation is allowed through. + * You only plan to provide self-service access via your Dev Portal. + - setting: | + `if_present` + description: | + By default, the ACE plugin only engages with a request when it matches an operation. If a request doesn't match, ACE lets the request pass through untouched. This means that non-matching requests aren't rejected, but ACE also won't perform authentication and authorization on them. This allows a request to still be processed by other plugins with a [lower priority](/gateway/entities/plugin/#plugin-priority) than ACE. + limitations: | + * All traffic outside of published APIs linked to an ACE-enabled {{site.base_gateway}} won't be access controlled, this must be configured with a different plugin. Dev Portal will not be able to protect all operations. + * Since Routes aren't protected by default in this mode, any mistyped or omitted operation in API entities could result in open access. + use-case: | + * You have an environment where some Gateway Services or Routes are governed by Dev Portal–exposed APIs (with ACE), while others are regular Routes that should be left alone. + * You already have existing traffic and other access controls in place and want to avoid interruption. +{% endtable %} \ No newline at end of file diff --git a/app/_kong_plugins/ace/index.md b/app/_kong_plugins/ace/index.md index 160f9979ff..c7f05a215b 100644 --- a/app/_kong_plugins/ace/index.md +++ b/app/_kong_plugins/ace/index.md @@ -40,51 +40,8 @@ related_resources: {:.warning} > **Important:** The Access Control Enforcement plugin can only be used with APIs that are linked to a control plane, which is a private beta feature. Contact your account manager for access. -The Access Control Enforcement (ACE) plugin manages developer access control to APIs published with Dev Portal. - -Previously, when you created an API catalog in Dev Portal and linked the APIs to a Gateway Service, {{site.konnect_short_name}} would automatically apply the {{site.konnect_short_name}} application auth (KAA) plugin automatically. API packages uses the ACE plugin instead to manage developer access control to APIs. Unlike the KAA plugin, the ACE plugin can link to control planes to configure access control and create operations for Gateway Services in those control planes. - -The ACE plugin runs *after* all other [authentication plugins](/plugins/?category=authentication) run. For example, if you have [Key Authentication](/plugins/key-auth/) configured and it rejects a request, the ACE plugin *will not* run. To allow for multiple authentication plugins, each must set the [`config.anonymous`](/plugins/ace/reference/#schema--config-anonymous) plugin configuration. Additionally, the choice to allow or reject an `anonymous` result after all authentication plugins have run needs to be controlled as described in [using multiple authentication methods](/gateway/authentication/#using-multiple-authentication-methods). +{% include /plugins/ace/ace-overview.md %} ## Route matching policy -When you configure the ACE plugin, you must set either `required` or `present` for [`config.match_policy`](/plugins/ace/reference/#schema--config-match-policy). This determines how the ACE plugin will behave when a request doesn't match an existing Route. - -Keep in mind that misconfigurations can overexpose unintended Routes. - -The following table describes what the `match_policy` values do and when to use each: -{% table %} -columns: - - title: Setting - key: setting - - title: Description - key: description - - title: Limitations - key: limitations - - title: Use cases - key: use-case -rows: - - setting: | - `required` - description: | - Requires every incoming request to match a defined operation from an API or API package in Dev Portal. If a request doesn't match, ACE rejects the request outright with a 404. All traffic will be rejected except operations or Routes in published APIs linked to an ACE-enabled {{site.base_gateway}}. - - {:.danger} - > **Warning:** Setting the [`match_policy`](/plugins/ace/reference/#schema--config-match-policy) to `required` can **block all traffic with a 404**. Any undefined endpoints will be blocked. If you accidentally enable this in your control planes, this could cause a potential outage in production. - limitations: | - * Shuts down all traffic outside of ACE-enabled Dev Portal APIs. - * If the plugin is improperly configured, potentially all traffic could be terminated. - use-case: | - * You want to lock down {{site.konnect_short_name}} so that only traffic that is part of an explicitly defined API operation is allowed through. - * You only plan to provide self-service access via your Dev Portal. - - setting: | - `if_present` - description: | - By default, the ACE plugin only engages with a request when it matches an operation. If a request doesn't match, ACE lets the request pass through untouched. This means that non-matching requests aren't rejected, but ACE also won't perform authentication and authorization on them. This allows a request to still be processed by other plugins with a [lower priority](/gateway/entities/plugin/#plugin-priority) than ACE. - limitations: | - * All traffic outside of published APIs linked to an ACE-enabled {{site.base_gateway}} won't be access controlled, this must be configured with a different plugin. Dev Portal will not be able to protect all operations. - * Since Routes aren't protected by default in this mode, any mistyped or omitted operation in API entities could result in open access. - use-case: | - * You have an environment where some Gateway Services or Routes are governed by Dev Portal–exposed APIs (with ACE), while others are regular Routes that should be left alone. - * You already have existing traffic and other access controls in place and want to avoid interruption. -{% endtable %} \ No newline at end of file +{% include /plugins/ace/ace-route-matching.md %} diff --git a/app/_redirects b/app/_redirects index e68beace51..5b5eb59804 100644 --- a/app/_redirects +++ b/app/_redirects @@ -143,6 +143,7 @@ /dev-portal/access-and-approval/ /dev-portal/self-service/ /dev-portal/publishing/ /catalog/apis/ /dev-portal/portal-customization/ /dev-portal/customizations/dev-portal-customizations/ +/dev-portal/api-catalog-and-packaging/ /dev-portal/api-packaging/ # Gateway LTS diff --git a/app/dev-portal/api-catalog-and-packaging.md b/app/dev-portal/api-packaging.md similarity index 65% rename from app/dev-portal/api-catalog-and-packaging.md rename to app/dev-portal/api-packaging.md index bf3a2e9a26..eecd9196dd 100644 --- a/app/dev-portal/api-catalog-and-packaging.md +++ b/app/dev-portal/api-packaging.md @@ -5,6 +5,7 @@ layout: reference products: - dev-portal + - catalog breadcrumbs: - /dev-portal/ @@ -26,7 +27,7 @@ description: | Learn how to package APIs in Dev Portal and what API packages are. related_resources: - text: Dev Portal APIs - url: /dev-portal/apis/ + url: /catalog/apis/ - text: Automate your API catalog with Dev Portal url: /how-to/automate-api-catalog/ - text: Automate your API catalog with Terraform @@ -104,53 +105,11 @@ Packaging APIs involves the following steps: ### ACE plugin -Previously, when you created an API catalog in Dev Portal and linked the APIs to a Gateway Service, {{site.konnect_short_name}} would automatically apply the {{site.konnect_short_name}} application auth (KAA) plugin automatically. - -API packages uses the ACE plugin instead to manage developer access control to APIs. Unlike the KAA plugin, the ACE plugin can link to control planes to configure access control and create operations for Gateway Services in those control planes. - -The ACE plugin runs *after* all other [authentication plugins](/plugins/?category=authentication) run. For example, if you have Key Authentication configured and it rejects a request, the ACE plugin *will not* run. If you're using the `config.anonymous` ACE plugin configuration, the [plugin priority](/gateway/entities/plugin/#plugin-priority) needs to be set in such a way that it executes after all other authentication plugins. For example, you can set a provisional priority of 949 so the plugin runs after KAA (which has a priority of 950). - +{% include plugins/ace/ace-overview.md %} #### Route matching policy -When you configure the ACE plugin, you must set either `required` or `present` for `config.match_policy`. This determines how the ACE plugin will behave when a request doesn't match an existing Route. - -The following table describes what the `match_policy` values do and when to use each: -{% table %} -columns: - - title: Setting - key: setting - - title: Description - key: description - - title: Limitations - key: limitations - - title: Use cases - key: use-case -rows: - - setting: | - `required` - description: | - Requires every incoming request to match a defined operation from an API or API package in Dev Portal. If a request doesn't match, ACE rejects the request outright with a 404. All traffic will be rejected except operations or Routes in published APIs linked to an ACE-enabled {{site.base_gateway}}. - - {:.danger} - > **Warning:** Setting the `match_policy` to `required` can **block all traffic with a 404**. Any undefined endpoints will be blocked. If you accidentally enable this in your control planes, this could cause a potential outage in production. - limitations: | - * Misconfigurations can overexpose unintended Routes. - * Shuts down all traffic outside of published Dev Portal APIs. - * If the plugin is improperly configured, potentially all traffic could be terminated. - use-case: | - * You want to lock down {{site.konnect_short_name}} so that only traffic that is part of an explicitly defined API operation is allowed through. - * You only plan to provide self-service access via your Dev Portal. - - setting: | - `if_present` - description: | - The ACE plugin only engages with a request when it matches an operation. If a request doesn't match, ACE lets the request pass through untouched. This means that non-matching requests aren't rejected, but ACE also won't perform authentication and authorization on them. This allows a request to still be processed by other plugins with a [lower priority](/gateway/entities/plugin/#plugin-priority) than ACE. - limitations: | - All traffic outside of published APIs linked to an ACE-enabled {{site.base_gateway}} won't be access controlled, this must be configured with a different plugin. Dev Portal will not be able to protect all operations. - use-case: | - * You have an environment where some Gateway Services or Routes are governed by Dev Portal–exposed APIs (with ACE), while others are regular Routes that should be left alone. - * You already have existing traffic and other access controls in place and want to avoid interruption. -{% endtable %} +{% include plugins/ace/ace-route-matching.md %} ### Package rate limits @@ -196,36 +155,47 @@ To package APIs with Dev Portal, you need: ### Associate a control plane -1. In {{site.konnect_short_name}}, navigate to **Dev Portal** > **APIs** in the sidebar. -1. Click your API. +1. In the {{site.konnect_short_name}} sidebar, click [**Catalog**](https://cloud.konghq.com/apis/). +1. Click **MyAPI**. 1. Click the **Gateway** tab. 1. Click **Link gateway**. -1. Select a control plane from the **Control plane** dropdown menu. +1. From the **Control plane** dropdown menu, select your control plane. 1. Select **Link to a control plane**. 1. In the Add the Access Control and Enforcement plugin settings, click **Add plugin**. 1. Click **Link gateway**. +1. Click the **API Specification** tab. +1. Click **Upload Spec**. +1. Click **Select file**. +1. Select your spec that matches your Routes. +1. Click **Save**. Your operations should now be autogenerated based on how your OpenAPI spec maps to your Routes. ### Assign operations to API packages -1. In {{site.konnect_short_name}}, navigate to **Dev Portal** > **APIs** in the sidebar. +1. In the {{site.konnect_short_name}} sidebar, click **Catalog**. 1. Click the **API packages** tab. 1. Click **Create API package**. -1. Enter a name in the **API package name** field. +1. In the **API package name** field, enter `Company package`. 1. Enable the Package rate limit and configure your rate limit. -1. Click **Add operations from APIs** in the API operations settings. -1. In the Add API operations pane, click your API and click **Add** next to the operations you want to package. +1. In the API operations settings, click **Add operations from APIs**. +1. In the Add API operations pane, click your API. +1. Click **Add** next to the operations you want to package. +1. Exit the Add API operations pane. 1. Click **Create API package**. +1. Click the **Specifications** tab. +1. Click **Generate spec from operations**. +1. Click **Save**. ### Publish packages to Dev Portal -1. In {{site.konnect_short_name}}, navigate to **Dev Portal** > **APIs** in the sidebar. +1. In the {{site.konnect_short_name}} sidebar, click **Catalog**. 1. Click the **API packages** tab. 1. Click your API package. 1. Click **Publish API**. -1. Select your Dev Portal from the **Portal** dropdown menu. -1. Select an auth strategy from the **Authentication strategy** dropdown menu. -1. Click **Publish API**. +1. From the **Portal** dropdown menu, select your Dev Portal. +1. From the **Authentication strategy** dropdown menu, select an auth strategy. +1. Click **Public**. +1. Click **Publish API**. Your API package will now be published to your Dev Portal. Published API packages appear the same as published APIs in the Dev Portal, and both allow developers to register applications with them. From 570846102beebfa1494f4b7cef498f81556743c0 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Tue, 20 Jan 2026 14:54:59 -0600 Subject: [PATCH 15/20] Move packaging to catalog instead Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/_redirects | 2 +- app/{dev-portal => catalog}/api-packaging.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) rename app/{dev-portal => catalog}/api-packaging.md (99%) diff --git a/app/_redirects b/app/_redirects index 5b5eb59804..a775838b30 100644 --- a/app/_redirects +++ b/app/_redirects @@ -143,7 +143,7 @@ /dev-portal/access-and-approval/ /dev-portal/self-service/ /dev-portal/publishing/ /catalog/apis/ /dev-portal/portal-customization/ /dev-portal/customizations/dev-portal-customizations/ -/dev-portal/api-catalog-and-packaging/ /dev-portal/api-packaging/ +/dev-portal/api-catalog-and-packaging/ /catalog/api-packaging/ # Gateway LTS diff --git a/app/dev-portal/api-packaging.md b/app/catalog/api-packaging.md similarity index 99% rename from app/dev-portal/api-packaging.md rename to app/catalog/api-packaging.md index eecd9196dd..941e426571 100644 --- a/app/dev-portal/api-packaging.md +++ b/app/catalog/api-packaging.md @@ -8,7 +8,7 @@ products: - catalog breadcrumbs: - - /dev-portal/ + - /catalog/ tags: - api-catalog - api-composition From f8161927e500034f71d0f27bd2477b7db63f7f91 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Wed, 21 Jan 2026 10:47:14 -0600 Subject: [PATCH 16/20] Add backlinks, add to index and landing pages Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/_how-tos/automate-api-catalog-with-terraform.md | 2 ++ app/_how-tos/automate-api-catalog.md | 2 ++ app/_indices/catalog.yaml | 1 + app/_indices/dev-portal.yaml | 1 + app/_landing_pages/catalog.yaml | 2 ++ app/_landing_pages/dev-portal.yaml | 2 ++ app/catalog/api-packaging.md | 8 ++++---- app/catalog/apis.md | 2 ++ 8 files changed, 16 insertions(+), 4 deletions(-) diff --git a/app/_how-tos/automate-api-catalog-with-terraform.md b/app/_how-tos/automate-api-catalog-with-terraform.md index 46bacd49b9..c183c3d1c4 100644 --- a/app/_how-tos/automate-api-catalog-with-terraform.md +++ b/app/_how-tos/automate-api-catalog-with-terraform.md @@ -110,6 +110,8 @@ faqs: next_steps: - text: Apply an authentication strategy to your APIs url: /dev-portal/auth-strategies/ + - text: Create API packages + url: /catalog/api-packaging/ --- ## Create an API diff --git a/app/_how-tos/automate-api-catalog.md b/app/_how-tos/automate-api-catalog.md index 49be951d21..1dcee45a1f 100644 --- a/app/_how-tos/automate-api-catalog.md +++ b/app/_how-tos/automate-api-catalog.md @@ -68,6 +68,8 @@ faqs: next_steps: - text: Apply an authentication strategy to your APIs url: /dev-portal/auth-strategies/ + - text: Create API packages + url: /catalog/api-packaging/ --- ## Create an API diff --git a/app/_indices/catalog.yaml b/app/_indices/catalog.yaml index b2b437980d..2c8147c452 100644 --- a/app/_indices/catalog.yaml +++ b/app/_indices/catalog.yaml @@ -6,6 +6,7 @@ sections: - title: APIs items: - path: /service-catalog/apis/ + - path: /catalog/api-packaging/ - path: /how-to/automate-api-catalog/ - path: /how-to/automate-api-catalog-with-terraform/ - path: /how-to/discover-and-govern-apis-with-service-catalog/ diff --git a/app/_indices/dev-portal.yaml b/app/_indices/dev-portal.yaml index 86db3c15d4..3d6ec78fe7 100644 --- a/app/_indices/dev-portal.yaml +++ b/app/_indices/dev-portal.yaml @@ -12,6 +12,7 @@ sections: - title: API catalog items: - path: /catalog/apis/ + - path: /catalog/api-packaging/ - path: /how-to/automate-api-catalog/ - path: /how-to/automate-api-catalog-with-terraform/ - title: Application registration diff --git a/app/_landing_pages/catalog.yaml b/app/_landing_pages/catalog.yaml index b9294533c2..748d2d1dee 100644 --- a/app/_landing_pages/catalog.yaml +++ b/app/_landing_pages/catalog.yaml @@ -50,6 +50,8 @@ rows: ctas: - text: APIs reference url: "/catalog/apis/" + - text: API packages + url: /catalog/api-packaging/ - text: Create an API catalog with the {{site.konnect_short_name}} API url: "/how-to/automate-api-catalog/" - text: Create an API catalog with Terraform diff --git a/app/_landing_pages/dev-portal.yaml b/app/_landing_pages/dev-portal.yaml index a2c3608b0f..13a0d09bf0 100644 --- a/app/_landing_pages/dev-portal.yaml +++ b/app/_landing_pages/dev-portal.yaml @@ -122,6 +122,8 @@ rows: url: "/how-to/automate-api-catalog-with-terraform/" - text: Create and publish APIs url: "/catalog/apis/" + - text: Create API packages + url: /catalog/api-packaging/ - text: Discover and govern APIs url: /how-to/discover-and-govern-apis-with-service-catalog/ diff --git a/app/catalog/api-packaging.md b/app/catalog/api-packaging.md index 941e426571..0afeda3110 100644 --- a/app/catalog/api-packaging.md +++ b/app/catalog/api-packaging.md @@ -1,11 +1,11 @@ --- -title: Dev Portal API packaging +title: Package APIs content_type: reference layout: reference products: - - dev-portal - catalog + - dev-portal breadcrumbs: - /catalog/ @@ -24,9 +24,9 @@ search_aliases: - API packaging - API bundle description: | - Learn how to package APIs in Dev Portal and what API packages are. + Learn how to package APIs in Catalog and Dev Portal and what API packages are. related_resources: - - text: Dev Portal APIs + - text: APIs reference url: /catalog/apis/ - text: Automate your API catalog with Dev Portal url: /how-to/automate-api-catalog/ diff --git a/app/catalog/apis.md b/app/catalog/apis.md index f0a116a5c5..bc46766a28 100644 --- a/app/catalog/apis.md +++ b/app/catalog/apis.md @@ -28,6 +28,8 @@ related_resources: url: /how-to/automate-api-catalog/ - text: Developer self-service and app registration url: /dev-portal/self-service/ + - text: Create API packages + url: /catalog/api-packaging/ faqs: - q: I'm using the Try it feature in the spec renderer to send requests from Dev Portal, but I'm getting a `401`. How do I fix it? a: If the published API has an [authentication strategy](/dev-portal/auth-strategies/) configured for it, you must include your key in the request. All requests without a key to the Service linked to the API are blocked if it is published with an auth strategy. From aba968dc59b8802bea9f95b6300766e5a801cd78 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Thu, 22 Jan 2026 09:49:11 -0600 Subject: [PATCH 17/20] Apply suggestions from code review Co-authored-by: lena-larionova <54370747+lena-larionova@users.noreply.github.com> --- app/_includes/plugins/ace/ace-overview.md | 9 +++++++-- app/_includes/plugins/ace/ace-route-matching.md | 2 +- app/catalog/api-packaging.md | 15 +++++++-------- 3 files changed, 15 insertions(+), 11 deletions(-) diff --git a/app/_includes/plugins/ace/ace-overview.md b/app/_includes/plugins/ace/ace-overview.md index 6cf5ac7556..05e4883371 100644 --- a/app/_includes/plugins/ace/ace-overview.md +++ b/app/_includes/plugins/ace/ace-overview.md @@ -1,5 +1,10 @@ The Access Control Enforcement (ACE) plugin manages developer access control to APIs published with Dev Portal. -Previously, when you created an API catalog in Dev Portal and linked the APIs to a Gateway Service, {{site.konnect_short_name}} would automatically apply the {{site.konnect_short_name}} application auth (KAA) plugin automatically. API packages uses the ACE plugin instead to manage developer access control to APIs. Unlike the KAA plugin, the ACE plugin can link to control planes to configure access control and create operations for Gateway Services in those control planes. +Previously, when you created an API catalog in Dev Portal and linked the APIs to a Gateway Service, {{site.konnect_short_name}} would automatically apply the {{site.konnect_short_name}} application auth (KAA) plugin. +API packages use the ACE plugin instead to manage developer access control to APIs. Unlike the KAA plugin, the ACE plugin can link to control planes to configure access control and create operations for Gateway Services. -The ACE plugin runs *after* all other [authentication plugins](/plugins/?category=authentication) run. For example, if you have [Key Authentication](/plugins/key-auth/) configured and it rejects a request, the ACE plugin *will not* run. To allow for multiple authentication plugins, each must set the [`config.anonymous`](/plugins/ace/reference/#schema--config-anonymous) plugin configuration. Additionally, the choice to allow or reject an `anonymous` result after all authentication plugins have run needs to be controlled as described in [using multiple authentication methods](/gateway/authentication/#using-multiple-authentication-methods). \ No newline at end of file +The ACE plugin runs *after* all other [authentication plugins](/plugins/?category=authentication) run. +For example, if you have [Key Authentication](/plugins/key-auth/) configured and it rejects a request, the ACE plugin *will not* run. + +To allow for multiple authentication plugins, each one must set the [`config.anonymous`](/plugins/ace/reference/#schema--config-anonymous) plugin configuration. +Additionally, the choice to allow or reject an `anonymous` result after all authentication plugins have run needs to be controlled as described in [using multiple authentication methods](/gateway/authentication/#using-multiple-authentication-methods). \ No newline at end of file diff --git a/app/_includes/plugins/ace/ace-route-matching.md b/app/_includes/plugins/ace/ace-route-matching.md index 54273adbd0..ea27cbf70f 100644 --- a/app/_includes/plugins/ace/ace-route-matching.md +++ b/app/_includes/plugins/ace/ace-route-matching.md @@ -32,7 +32,7 @@ rows: description: | By default, the ACE plugin only engages with a request when it matches an operation. If a request doesn't match, ACE lets the request pass through untouched. This means that non-matching requests aren't rejected, but ACE also won't perform authentication and authorization on them. This allows a request to still be processed by other plugins with a [lower priority](/gateway/entities/plugin/#plugin-priority) than ACE. limitations: | - * All traffic outside of published APIs linked to an ACE-enabled {{site.base_gateway}} won't be access controlled, this must be configured with a different plugin. Dev Portal will not be able to protect all operations. + * All traffic outside of published APIs linked to an ACE-enabled {{site.base_gateway}} won't be access controlled; this must be configured with a [different authentication plugin](/plugins/?category=authentication). Dev Portal will not be able to protect all operations. * Since Routes aren't protected by default in this mode, any mistyped or omitted operation in API entities could result in open access. use-case: | * You have an environment where some Gateway Services or Routes are governed by Dev Portal–exposed APIs (with ACE), while others are regular Routes that should be left alone. diff --git a/app/catalog/api-packaging.md b/app/catalog/api-packaging.md index 0afeda3110..46471827df 100644 --- a/app/catalog/api-packaging.md +++ b/app/catalog/api-packaging.md @@ -12,7 +12,8 @@ breadcrumbs: tags: - api-catalog - api-composition - +min_version: + gateway: '3.13' works_on: - konnect api_specs: @@ -92,8 +93,6 @@ flowchart LR end 1 --> 5 & 6 2 --> 7 & 8 & 3 & 4 - style subGraph2 fill:#C8E6C9 - style subGraph1 fill:#BBDEFB {% endmermaid %} @@ -101,7 +100,7 @@ Packaging APIs involves the following steps: 1. Create an API and attach an OpenAPI spec. Operations from your API's OpenAPI spec should overlap with Routes to ensure requests will be routed to the correct Service. Gateway routing configuration isn't directly modified by adding operations. 1. Link a control plane to allow developer consumption. 1. Apply the Access Control Enforcement (ACE) plugin globally. -1. Create an API package by adding operations and package rate limits. Operations are automatically mapped to Routes using your API's OpenAPI spec or you can create them manually. The Gateway configuration isn't directly modified– any unmatched operations will be highlighted to indicate that a user Gateway Manager permissions needs to perform an action. +1. Create an API package by adding operations and package rate limits. Operations are automatically mapped to Routes using your API's OpenAPI spec or you can create them manually. The Gateway configuration isn't directly modified – any unmatched operations will be highlighted to indicate that a user needs Gateway Manager permissions needs to perform an action. ### ACE plugin @@ -115,7 +114,7 @@ Packaging APIs involves the following steps: You can set individual rate limits on an API package as well as operations in that package. Keep the following in mind when configuring rate limits: * API package rate limits apply across all operations in the API package **cumulatively**, not individually. -* Each Operation in an API Package can additionally have an individual rate limit defined. When an operation-level override is present, the package-level limit is ignored for that operation. +* Each operation in an API Package can additionally have an individual rate limit defined. When an operation-level override is present, the package-level limit is ignored for that operation. * API package rate limits are applied simultaneously with rate limits from other plugins on gateway entities: * Requests that are under the current limit for the Service and API Package will be counted towards both. * Requests that surpass the rate limit of an API package won't be counted towards rate limits applied from other rate limiting plugins. @@ -132,11 +131,11 @@ Because an operation-level override is present, the package-level limit is ignor When configuring API packages, keep the following limitations in mind: -* If you have two endpoints in your spec, one with a trailing slash one without, both are generated as the same operation. +* If you have two endpoints in your spec, one with a trailing slash and one without, both are generated as the same operation. * If two operations have the same path and method, they are generated as the same operation. * All operations for a control plane are removed when you unlink the control plane. * APIs can only be mapped to one control plane at a time. -* You can't change a version or edit a spec for an API if it would remove an operation because this would result in a breaking change. The recommended method to remove an operation is to unlink the control plane from the API. +* You can't change a version or edit a spec for an API if it would remove an operation because this would result in a breaking change. To remove an operation, we recommend unlinking the control plane from the API. ## Package APIs with Dev Portal @@ -146,7 +145,7 @@ This guide shows you how to create an API package in the {{site.konnect_short_na To package APIs with Dev Portal, you need: * A v3 Dev Portal created in {{site.konnect_short_name}} -* A [Gateway Service](/gateway/entities/service/#set-up-a-gateway-service) and/or [Route](/gateway/entities/route/#set-up-a-route) added to your control plane ({{site.base_gateway}} 3.12 or later) +* A [Gateway Service](/gateway/entities/service/#set-up-a-gateway-service) and/or [Route](/gateway/entities/route/#set-up-a-route) added to your control plane ({{site.base_gateway}} 3.13 or later) * The following roles: * Editor role for APIs * Publisher role for the API and API package From 4e43fbf6fdb59dd7fe233aa9fedf3ae4be9326a2 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Thu, 22 Jan 2026 09:58:52 -0600 Subject: [PATCH 18/20] Appease vale Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- .github/styles/base/Dictionary.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/styles/base/Dictionary.txt b/.github/styles/base/Dictionary.txt index df37ddefc9..ef0725557a 100644 --- a/.github/styles/base/Dictionary.txt +++ b/.github/styles/base/Dictionary.txt @@ -903,6 +903,7 @@ ungrouped Unicode unicode unix +unlinking unmanaged unmarshalled unnamespaced From 2d456cf4f78333ab20ff3d087d4e3a6fa5f46c11 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Thu, 22 Jan 2026 11:18:16 -0600 Subject: [PATCH 19/20] feat(dev-portal): API packaging how to (#3580) * Start drafting how to Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> * Rename how to and revise some of the steps for UI changes as well as making more specific Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> * Apply more step changes, draft-ish the validation step Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> * Add example spec, basic validate, fix some steps Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> * Minor phrasing cleanup Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> * fix broken links * actually fix broken link * Apply PM feedback, backlinks Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: lena-larionova <54370747+lena-larionova@users.noreply.github.com> * Update GW min version Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --------- Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> Co-authored-by: lena-larionova <54370747+lena-larionova@users.noreply.github.com> --- .../automate-api-catalog-with-terraform.md | 2 + app/_how-tos/automate-api-catalog.md | 2 + ...er-and-govern-apis-with-service-catalog.md | 2 + app/_how-tos/package-apis-with-dev-portal.md | 323 ++++++++++++++++++ app/_includes/prereqs/dev-portal-create-ui.md | 8 + app/_indices/catalog.yaml | 1 + app/_indices/dev-portal.yaml | 1 + app/catalog/api-packaging.md | 44 +-- app/catalog/apis.md | 4 +- 9 files changed, 354 insertions(+), 33 deletions(-) create mode 100644 app/_how-tos/package-apis-with-dev-portal.md create mode 100644 app/_includes/prereqs/dev-portal-create-ui.md diff --git a/app/_how-tos/automate-api-catalog-with-terraform.md b/app/_how-tos/automate-api-catalog-with-terraform.md index c183c3d1c4..7ab75bfc89 100644 --- a/app/_how-tos/automate-api-catalog-with-terraform.md +++ b/app/_how-tos/automate-api-catalog-with-terraform.md @@ -36,6 +36,8 @@ related_resources: url: /dev-portal/application-registration/ - text: Application authentication strategies url: /dev-portal/auth-strategies/ + - text: Package APIs with Dev Portal + url: /how-to/package-apis-with-dev-portal/ prereqs: skip_product: true inline: diff --git a/app/_how-tos/automate-api-catalog.md b/app/_how-tos/automate-api-catalog.md index 1dcee45a1f..e7dedef924 100644 --- a/app/_how-tos/automate-api-catalog.md +++ b/app/_how-tos/automate-api-catalog.md @@ -52,6 +52,8 @@ related_resources: url: /dev-portal/application-registration/ - text: Application authentication strategies url: /dev-portal/auth-strategies/ + - text: Package APIs with Dev Portal + url: /how-to/package-apis-with-dev-portal/ faqs: - q: I just edited or deleted my spec, document, page, or snippet. Why don't I immediately see these changes live in the Dev Portal? a: If you recently viewed the related content, your browser might be serving a cached version of the page. To fix this, you can clear your browser cache and refresh the page. diff --git a/app/_how-tos/discover-and-govern-apis-with-service-catalog.md b/app/_how-tos/discover-and-govern-apis-with-service-catalog.md index b1a9e8d70d..41cf9a440f 100644 --- a/app/_how-tos/discover-and-govern-apis-with-service-catalog.md +++ b/app/_how-tos/discover-and-govern-apis-with-service-catalog.md @@ -21,6 +21,8 @@ related_resources: url: /catalog/integrations/ - text: AWS API Gateway reference url: /catalog/integrations/aws-api-gateway/ + - text: Package APIs with Dev Portal + url: /how-to/package-apis-with-dev-portal/ automated_tests: false tldr: q: How do I discover and govern third-party APIs in {{site.konnect_short_name}}? diff --git a/app/_how-tos/package-apis-with-dev-portal.md b/app/_how-tos/package-apis-with-dev-portal.md new file mode 100644 index 0000000000..899f54f069 --- /dev/null +++ b/app/_how-tos/package-apis-with-dev-portal.md @@ -0,0 +1,323 @@ +--- +title: "Package APIs with Dev Portal" +description: "Learn how to compose existing APIs in Dev Portal into API packages." +content_type: how_to +related_resources: + - text: About Dev Portal + url: /dev-portal/ + - text: API packaging reference + url: /catalog/api-packaging/ +automated_tests: false +products: + - dev-portal + - gateway + - catalog +min_version: + gateway: '3.13' +works_on: + - konnect +tools: + - deck +tags: + - api-catalog + - api-composition + +tldr: + q: How do I create API packages from existing Dev Portal APIs? + a: | + Packaging APIs involves the following steps: + 1. Create an API and attach an OpenAPI spec. + 1. Apply the Access Control Enforcement (ACE) plugin globally on the control plane you want to link. + 1. Link a control plane to the API to allow developer consumption. + 1. Create an API package by adding operations and package rate limits. + 1. Publish the API package to Dev Portal. +prereqs: + inline: + - title: "{{site.konnect_short_name}} roles" + content: | + To recover create API packages, you need the following [roles](/konnect-platform/teams-and-roles/): + * Editor role for APIs + * Publisher role for the API and API package + * API Creator + icon_url: /assets/icons/gateway.svg + - title: Dev Portal + include_content: prereqs/dev-portal-create-ui + icon_url: /assets/icons/dev-portal.svg + - title: Dev Portal APIs + content: | + To complete this guide, you'll need an API in Catalog: + 1. In the {{site.konnect_short_name}} sidebar, click **Catalog**. + 1. Click [**New API**](https://cloud.konghq.com/apis/create). + 1. In the **API name** field, enter `MyAPI`. + 1. Click **Create**. + icon_url: /assets/icons/dev-portal.svg + - title: Required entities + content: | + For this tutorial, you’ll need {{site.base_gateway}} entities, like Gateway Services and Routes, pre-configured. These entities are essential for {{site.base_gateway}} to function but installing them isn’t the focus of this guide. + + 1. Run the following command: + + ```yaml + echo ' + _format_version: "3.0" + services: + - name: example-service + url: http://httpbin.konghq.com/anything + routes: + - name: example-route + paths: + - "/anything" + methods: + - GET + - PUT + - POST + - PATCH + - DELETE + service: + name: example-service + ' | deck gateway apply - + ``` + + To learn more about entities, you can read our [entities documentation](/gateway/entities/). + - title: API specification + content: | + To complete this guide, you'll need an API specification that matches the Route you created. {{site.konnect_catalog}} uses the spec to add operations to your API package. + + ```sh + cat > example-api-spec.yaml << 'EOF' + openapi: 3.0.0 + info: + title: Example API + description: Example API service for testing and documentation + version: 1.0.0 + + servers: + - url: http://httpbin.konghq.com + description: Backend service (HTTP only, port 80) + + paths: + /anything: + get: + summary: Get anything + description: Echo back GET request details + operationId: getAnything + tags: + - Echo + responses: + '200': + description: Successful response + content: + application/json: + schema: + $ref: '#/components/schemas/EchoResponse' + '426': + description: Upgrade Required (HTTPS redirect) + + post: + summary: Post anything + description: Echo back POST request details + operationId: postAnything + tags: + - Echo + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + '200': + description: Successful response + content: + application/json: + schema: + $ref: '#/components/schemas/EchoResponse' + '426': + description: Upgrade Required (HTTPS redirect) + + put: + summary: Put anything + description: Echo back PUT request details + operationId: putAnything + tags: + - Echo + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + '200': + description: Successful response + content: + application/json: + schema: + $ref: '#/components/schemas/EchoResponse' + '426': + description: Upgrade Required (HTTPS redirect) + + patch: + summary: Patch anything + description: Echo back PATCH request details + operationId: patchAnything + tags: + - Echo + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: true + responses: + '200': + description: Successful response + content: + application/json: + schema: + $ref: '#/components/schemas/EchoResponse' + '426': + description: Upgrade Required (HTTPS redirect) + + delete: + summary: Delete anything + description: Echo back DELETE request details + operationId: deleteAnything + tags: + - Echo + responses: + '200': + description: Successful response + content: + application/json: + schema: + $ref: '#/components/schemas/EchoResponse' + '426': + description: Upgrade Required (HTTPS redirect) + + components: + schemas: + EchoResponse: + type: object + properties: + args: + type: object + description: Query parameters + data: + type: string + description: Request body data + files: + type: object + description: Uploaded files + form: + type: object + description: Form data + headers: + type: object + description: Request headers + json: + type: object + description: JSON request body + method: + type: string + description: HTTP method used + origin: + type: string + description: Origin IP address + url: + type: string + description: Request URL + + x-kong-service: + name: example-service + host: httpbin.konghq.com + port: 80 + protocol: http + path: /anything + retries: 5 + connect_timeout: 60000 + write_timeout: 60000 + read_timeout: 60000 + + x-kong-route: + name: example-route + protocols: [http, https] + methods: [GET, POST, PUT, PATCH, DELETE] + paths: [/anything] + strip_path: true + preserve_host: false + https_redirect_status_code: 426 + EOF + ``` + icon_url: /assets/icons/dev-portal.svg + + +cleanup: + inline: + - title: Clean up {{site.konnect_short_name}} environment + include_content: cleanup/platform/konnect + icon_url: /assets/icons/gateway.svg +--- + +You can compose [API packages](/catalog/api-packaging/) from existing APIs in Dev Portal. API packages allow you to: +* Create distinct APIs for specific use cases or partners based on existing API operations. +* Link to multiple Gateway Services and/or Routes for developer self-service and application registration. +* Apply rate limiting policies to an API Package, or per operation. +* Manage role-based access control for specific developers and teams. + +## Associate a control plane + +To allow developers to consume your API, you must first link an API Gateway and control plane to your API. + +Operations from your API's OpenAPI spec should overlap with Routes to ensure requests will be routed to the correct Service. Gateway routing configuration isn't directly modified by adding operations. +1. In the {{site.konnect_short_name}} sidebar, click [**Catalog**](https://cloud.konghq.com/apis/). +1. Click **MyAPI**. +1. Click the **Gateway** tab. +1. Click **Link gateway**. +1. From the **Control plane** dropdown menu, select "quickstart". +1. Select **Link to a control plane**. +1. In the Add the Access Control and Enforcement plugin settings, click **Add plugin**. +1. Click **Link gateway**. +1. Click the **API Specification** tab. +1. Click **Upload Spec**. +1. Click **Select file**. +1. Select `example-api-spec.yaml`. +1. Click **Save**. + +## Assign operations to API packages + +Now, you can create an API package by picking operations from your API. Operations are automatically mapped to Routes using your API's OpenAPI spec. The Gateway configuration isn't directly modified – any unmatched operations will be highlighted to indicate that a user needs Gateway Manager permissions to perform an action. + +1. In the {{site.konnect_short_name}} sidebar, click **Catalog**. +1. Click the **API packages** tab. +1. Click **Create API package**. +1. In the **API package name** field, enter `Company package`. +1. Enable the Package rate limit. +1. For the rate limit, enter `5` and select "Minute". +1. In the API operations settings, click **Add operations from APIs**. +1. In the Add API operations pane, click **MyAPI** +1. For GET `/anything`, click **Add**. +1. For PUT `/anything`, click **Add**. +1. For POST `/anything`, click **Add**. +1. Exit the Add API operations pane. +1. Click **Create API package**. +1. Click the **Specifications** tab. +1. Click **Generate spec from operations**. +1. Click **Save**. + +## Publish API packages to Dev Portal +Now you can make the API packages available to developers by publishing them to a Dev Portal. +1. In the {{site.konnect_short_name}} sidebar, click **Catalog**. +1. Click the **API packages** tab. +1. Click **Company package**. +1. Click **Publish API**. +1. From the **Portal** dropdown menu, select your Dev Portal. +1. From the **Authentication strategy** dropdown menu, select "Disabled". +1. Click **Public**. +1. Click **Publish API**. + +Your API package will now be published to your Dev Portal. Published API packages appear the same as published APIs in the Dev Portal, and both allow developers to register applications with them. + +## Validate + +Now that you've published your API package, you can verify that it was successfully published by navigating to your Dev Portal's URL. You can find your Dev Portal's URL by navigating to the [Dev Portal overview](https://cloud.konghq.com/portals/) in the {{site.konnect_short_name}} UI. \ No newline at end of file diff --git a/app/_includes/prereqs/dev-portal-create-ui.md b/app/_includes/prereqs/dev-portal-create-ui.md new file mode 100644 index 0000000000..b7bfce4d88 --- /dev/null +++ b/app/_includes/prereqs/dev-portal-create-ui.md @@ -0,0 +1,8 @@ +For this tutorial, you’ll need a Dev Portal pre-configured. If you don't have these settings already configured, follow these steps to pre-configure it: + +1. In the {{site.konnect_short_name}} sidebar, click **Dev Portal**. +1. Click [**New portal**](https://cloud.konghq.com/portals/create). +1. Enter a name for your Dev Portal. +1. Click **Create and continue**. +1. Customize your Dev Portal's appearance. +1. Click **Save**. \ No newline at end of file diff --git a/app/_indices/catalog.yaml b/app/_indices/catalog.yaml index 2c8147c452..59ba0e632a 100644 --- a/app/_indices/catalog.yaml +++ b/app/_indices/catalog.yaml @@ -10,6 +10,7 @@ sections: - path: /how-to/automate-api-catalog/ - path: /how-to/automate-api-catalog-with-terraform/ - path: /how-to/discover-and-govern-apis-with-service-catalog/ + - path: /how-to/package-apis-with-dev-portal/ - title: Services and scorecards items: - path: /catalog/scorecards/ diff --git a/app/_indices/dev-portal.yaml b/app/_indices/dev-portal.yaml index 3d6ec78fe7..2c002703e7 100644 --- a/app/_indices/dev-portal.yaml +++ b/app/_indices/dev-portal.yaml @@ -15,6 +15,7 @@ sections: - path: /catalog/api-packaging/ - path: /how-to/automate-api-catalog/ - path: /how-to/automate-api-catalog-with-terraform/ + - path: /how-to/package-apis-with-dev-portal/ - title: Application registration items: - title: Developer sign-up diff --git a/app/catalog/api-packaging.md b/app/catalog/api-packaging.md index 46471827df..ae8edbad42 100644 --- a/app/catalog/api-packaging.md +++ b/app/catalog/api-packaging.md @@ -37,8 +37,8 @@ related_resources: url: /dev-portal/auth-strategies/ --- - +{:.success} +> This is a reference guide, you can also follow along with our [Package APIs for partners with Dev Portal](/how-to/package-apis-with-dev-portal/) tutorial. You can compose API packages from existing APIs in Dev Portal. API packages allow you to: * Create distinct APIs for specific use cases or partners based on existing API operations. @@ -151,44 +151,24 @@ To package APIs with Dev Portal, you need: * Publisher role for the API and API package * API Creator * [An API created](/dev-portal/apis/) with an [OpenAPI spec](/dev-portal/apis/#api-specs) associated with it +* A Gateway control plane linked to your API in **Catalog** > **APIs** -### Associate a control plane - -1. In the {{site.konnect_short_name}} sidebar, click [**Catalog**](https://cloud.konghq.com/apis/). -1. Click **MyAPI**. -1. Click the **Gateway** tab. -1. Click **Link gateway**. -1. From the **Control plane** dropdown menu, select your control plane. -1. Select **Link to a control plane**. -1. In the Add the Access Control and Enforcement plugin settings, click **Add plugin**. -1. Click **Link gateway**. -1. Click the **API Specification** tab. -1. Click **Upload Spec**. -1. Click **Select file**. -1. Select your spec that matches your Routes. -1. Click **Save**. +### Create an API package -Your operations should now be autogenerated based on how your OpenAPI spec maps to your Routes. - -### Assign operations to API packages - -1. In the {{site.konnect_short_name}} sidebar, click **Catalog**. +1. In {{site.konnect_short_name}}, click **Catalog**. 1. Click the **API packages** tab. 1. Click **Create API package**. -1. In the **API package name** field, enter `Company package`. +1. In the **API package name** field, enter a name for your package. 1. Enable the Package rate limit and configure your rate limit. -1. In the API operations settings, click **Add operations from APIs**. -1. In the Add API operations pane, click your API. -1. Click **Add** next to the operations you want to package. -1. Exit the Add API operations pane. -1. Click **Create API package**. -1. Click the **Specifications** tab. -1. Click **Generate spec from operations**. -1. Click **Save**. +1. Click **Add operations from APIs** in the API operations settings. +1. In the Add API operations pane, click your API and click **Add** next to the operations you want to package. +1. Click **Create API package**. + +Your operations should now be autogenerated based on how your OpenAPI spec maps to your Routes. ### Publish packages to Dev Portal -1. In the {{site.konnect_short_name}} sidebar, click **Catalog**. +1. In {{site.konnect_short_name}}, click **Catalog**. 1. Click the **API packages** tab. 1. Click your API package. 1. Click **Publish API**. diff --git a/app/catalog/apis.md b/app/catalog/apis.md index bc46766a28..22fd0ceeb7 100644 --- a/app/catalog/apis.md +++ b/app/catalog/apis.md @@ -28,7 +28,9 @@ related_resources: url: /how-to/automate-api-catalog/ - text: Developer self-service and app registration url: /dev-portal/self-service/ - - text: Create API packages + - text: Package APIs with Dev Portal + url: /how-to/package-apis-with-dev-portal/ + - text: API packages reference url: /catalog/api-packaging/ faqs: - q: I'm using the Try it feature in the spec renderer to send requests from Dev Portal, but I'm getting a `401`. How do I fix it? From 5737d8091c3f5f20c374ccc3e3fb5836247af605 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Thu, 22 Jan 2026 12:00:04 -0600 Subject: [PATCH 20/20] Update app/catalog/api-packaging.md Co-authored-by: lena-larionova <54370747+lena-larionova@users.noreply.github.com> --- app/catalog/api-packaging.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/app/catalog/api-packaging.md b/app/catalog/api-packaging.md index ae8edbad42..07dc6d6017 100644 --- a/app/catalog/api-packaging.md +++ b/app/catalog/api-packaging.md @@ -141,6 +141,8 @@ When configuring API packages, keep the following limitations in mind: This guide shows you how to create an API package in the {{site.konnect_short_name}} UI. +For an end-to-end tutorial with sample data that walks you through setting up and using API Packages, see [Package APIs with Dev Portal](/how-to/package-apis-with-dev-portal/). + ### Prerequisites To package APIs with Dev Portal, you need: