feat(dev-portal): API packaging how to

app/_data/schemas/frontmatter/tags.json

@@ -12,6 +12,7 @@
     "analytics",
     "anthropic",
     "api-catalog",
+    "api-composition",
     "api-products",
     "apiops",
     "application-registration",

app/_how-tos/package-apis-for-partners-with-dev-portal.md

@@ -0,0 +1,108 @@
+---
+title: "Package APIs for partners with Dev Portal"
+description: "Learn how to package existing APIs in Dev Portal into API packages for partners."
+content_type: how_to
+related_resources:
+  - text: About Dev Portal
+    url: /dev-portal/
+  - text: Dev Portal API packaging reference
+    url: /dev-portal/api-catalog-and-packaging/
+automated_tests: false
+products:
+    - konnect
+    - dev-portal
+
+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. 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.
+prereqs:
+  show_works_on: false
+  inline:
+    - title: "{{site.konnect_product_name}}"
+      include_content: prereqs/products/konnect-account-only
+      icon_url: /assets/icons/gateway.svg
+    - 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 Dev Portal. 
+        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
+  entities:
+    services:
+        - example-service
+    routes:
+        - example-route
+
+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 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.
+
+### Associate a control plane
+
+To allow developers to consume your API, you must first link an API Gateway and control plane to your API.
+
+1. In {{site.konnect_short_name}}, click **Catalog**.
+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**.
+
+### Assign operations to API packages
+
+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 `Partner 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. Click **Create API package**. 
+
+### Publish packages to Dev Portal
+
+1. In {{site.konnect_short_name}}, navigate to **Dev Portal** > **APIs** in the sidebar.
+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**. 
+
+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.

app/_includes/prereqs/dev-portal-create-ui.md

@@ -0,0 +1,4 @@
+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** to [create a Dev Portal](https://cloud.konghq.com/portals/create).

app/dev-portal/api-catalog-and-packaging.md

@@ -0,0 +1,221 @@
+---
+title: Dev Portal API 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
+  - API bundle
+description: | 
+    Learn how to package APIs in Dev Portal and what API packages are.
+related_resources:
+  - 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/
+---
+
+{:.success}
+> This is a reference guide, you can also follow along with our [Package APIs for partners with Dev Portal](/how-to/package-apis-for-partners-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.
+* 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:
+<!--vale off-->
+{% 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 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. 
+    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 %}
+<!--vale on-->
+
+## 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 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:
+
+<!--vale off-->
+{% 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 %}
+<!--vale on-->
+
+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.
+
+### 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).
+
+
+#### 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 %}
+
+### 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. 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.
+  * 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
+* **Operation 1**: 5 requests 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
+
+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 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.
+
+## 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}}
+* 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
+  * 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**
+
+### Create an API package
+
+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 a name for your 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. 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 {{site.konnect_short_name}}, 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**. 
+
+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.