API Products

API Products are only available with classic Dev Portals (v2)
The new Dev Portal (v3) provides a more modern approach to API creation and publishing. See Automate your API catalog with Dev Portal for a complete tutorial about how to create and publish APIs in v3 Dev Portal.

API Products bundles and manages multiple Gateway Services. Each API product consists of at least one API product version, and each API product version is connected to a Gateway Service. You can document your Services and publish API products to a classic Dev Portal (v2) for consumption.

The API Product dashboard is the place to manage API products, versions, and documentation. The dashboard is available by clicking any API product from API Products in the sidebar.

Here are some of the things you can do from the API Product dashboard:

• Configure an API product
• Publish an API product to the v2 Dev Portal
• Manage API product versions
• View traffic, error, and latency data

Note: API products can only be published to the v2 Dev Portal in the geographic region you currently have selected. To publish to a v2 Dev Portal in a different region, switch geos using the control in the bottom-left corner of Konnect.

A Konnect API product version is linked to a Gateway Service inside a control plane. As such, the configurations or plugins that are associated with the Gateway Service are also associated with the API product version.

API products can have multiple API product versions, and each version can be linked to a Gateway Service. API products can be made available in multiple environments by linking API product versions to Gateway Services in different control planes. You can also associate an API spec with a product version and make the spec accessible in the v2 Dev Portal.

A common use case is environment specialization. For example, if you have three control planes for development, staging, and production, you can manage which environment the API product version is available in by linking an API product version to a Gateway Service in that control plane. You might have v1 running in production, and be actively working on v2 in development. Once it’s ready to test, you’d create v2 in staging before finally creating v2 in production alongside v1.

The analytics dashboard shown in the API product Overview is a high level overview of traffic, error, and latency for the API product. These reports are generated automatically based on the traffic to the API product.

A core function of the Dev Portal is publishing API product descriptions, documentation, and API specs. Developers can use the v2 Dev Portal to access, consume, and register new applications against your API product.

Manage your API product’s documentation directly within the Documentation section of the API Product dashboard. After uploading documentation, you can edit it seamlessly from the Konnect dashboard. Documentation is accessible after the API product is published.

You can provide extended descriptions of your API products with a Markdown (.md) file. The contents of this file will be displayed as the introduction to your API in the v2 Dev Portal. API product descriptions can be any markdown document that describes your Service such as:

• Release notes
• Support and SLA
• Business context and use cases
• Deployment workflows

Interactive markdown renderer

The integrated markdown editor allows you to　create and edit documentation directly within Konnect. It supports:

• Code syntax highlighting for Bash, JSON, Go, and JavaScript
• Rendering UML diagrams and flowcharts via Mermaid and PlantUML
• Emojis

You can insert Mermaid and PlantUML diagrams by using a language-specific identifier immediately following the triple backtick (```) notation that initiates the code block:

• ```mermaid
• ```plantuml

API specifications

API specifications, or specs, can be uploaded and attached to a specific API product version within API products. Konnect accepts OpenAPI (Swagger) specs in YAML or JSON.

Note: Supported version fields are swagger: "2.0" and those that match openapi: x.y.z (for example: openapi: 3.1.0). OpenAPI spec versions 2.0 or later are supported.

Once you’ve uploaded the spec, you can also preview the way the spec will render, including the methods available, endpoint descriptions, and example values. You’ll also be able to filter by tag when in full-page view.

Using API Products, you can create and manage API products to productize your Services. Each API product consists of at least one API product version, and each API product version is connected to a Gateway Service. Creating API products is the first step in making your APIs and their documentation available to developers. API products are geo-specific and are not shared between geographic regions.

This guide will walk you through creating an API product and productizing it by deploying it to the v2 Dev Portal.

Prerequisites

• A Service created.
• The API Products Publisher role for the API product you want to publish
• At least the Viewer role for the v2 Dev Portal you want to publish to

Create an API product

 curl -X POST "https://us.api.konghq.com/v2/api-products" \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "API Product"
     }'

Create an API product version

 curl -X POST "https://us.api.konghq.com/v2/api-products/$API_PRODUCT_ID/product-versions" \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "v1"
     }'

 curl -X POST "https://us.api.konghq.com/v2/api-products/$API_PRODUCT_ID/product-versions" \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "v1",
       "gateway_service": {
         "control_plane_id": "'$CONTROL_PLANE_ID'",
         "id": "'$SERVICE_ID'"
       }
     }'

Publish an API product

 curl -X PATCH "https://us.api.konghq.com/v2/api-products/$API_PRODUCT_ID" \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "portal_ids": [
         "'$V2_DEV_PORTAL_ID'"
       ]
     }'

 curl -X POST "https://us.api.konghq.com/v2/portals/$V2_DEV_PORTAL_ID/product-versions" \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "product_version_id": "'$API_PRODUCT_VERSION_ID'",
       "auth_strategy_ids": "'$AUTH_STRATEGY_ID'",
       "application_registration_enabled": true,
       "auto_approve_registration": false,
       "publish_status": "published",
       "deprecated": false
     }'