API catalog

This is a reference guide, you can also follow along with our tutorials:

• Automate your API catalog with the Konnect API
• Automate your API catalog with Terraform

An API is the interface that you publish to your end customer. They can, and should, include an OpenAPI or AsyncAPI specification or additional documentation to help users get started with your API.

Additionally, you can link your API to a Gateway Service to allow developers to register applications for your specific APIs.

To create an API, do one of the following:

curl -X POST "https://us.api.konghq.com/v3/apis" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "MyAPI",
       "attributes": {
         "env": [
           "development"
         ],
         "domains": [
           "web",
           "mobile"
         ]
       }
     }'

echo '
resource "konnect_api" "my_api" {
  attributes  = "{ \"see\": \"documentation\" }"
  description = "...my_description..."
  labels = {
    key = "value"
  }
  name         = "MyAPI"
  slug         = "my-api-v1"
  spec_content = "...my_spec_content..."
  version      = "...my_version..."
}
' >> main.tf

When you create an API, you can optionally specify the version as a free text string.

While you can use any version style, we recommend the following:

• Semantic versioning (for example 1.0.0, 2.1.0) is best supported for default ordering
• Create a unique API for each major version, since APIs must be unique based on the combination of name + version

The API slug determines Dev Portal URL routing in your list of APIs, which defaults to a name and version (major version if semantic versioning) in slug form. For example, if your API is named my-test-api and the version is 3, this will default to my-test-api-3. If a version isn’t specified, then name is used as the unique identifier.

API specification versions

If you upload OpenAPI or AsyncAPI specifications when you create the API, the API version will default to and be constrained by the version in the specification. You can specify multiple versions of API specifications in the API entity. Ideally, use multiple versions of API specs for minor versions of an API. When multiple versions are specified, a selector displays in the generated API reference to switch between versions of the API specification.

The API entity’s version property is treated as “current”, meaning it is the version that will be listed in your list of APIs.

To version an API, do one of the following:

curl -X POST "https://us.api.konghq.com/v3/apis/$API_ID/versions" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "version": "1.0.0",
       "spec": {
         "content": "{\"openapi\":\"3.0.3\",\"info\":{\"title\":\"Example API\",\"version\":\"1.0.0\"},\"paths\":{\"/example\":{\"get\":{\"summary\":\"Example endpoint\",\"responses\":{\"200\":{\"description\":\"Successful response\"}}}}}}"
       }
     }'

echo '
resource "konnect_api_version" "my_apiversion" {
  api_id = "9f5061ce-78f6-4452-9108-ad7c02821fd5"
  spec = {
    content = "{\"openapi\":\"3.0.3\",\"info\":{\"title\":\"Example API\",\"version\":\"1.0.0\"},\"paths\":{\"/example\":{\"get\":{\"summary\":\"Example endpoint\",\"responses\":{\"200\":{\"description\":\"Successful response\"}}}}}}"
  }
  version = "1.0.0"
}
' >> main.tf

API spec validation

All API specification files are validated during upload, although invalid specifications are permitted. If specifications are invalid, features like generated documentation and search may be degraded.

Konnect looks for the following during spec validation:

• Specs must be valid JSON or YAML.
• Spec should be valid according to the OpenAPI 2.0, 3.0.x, or 3.1.x specification or the AsyncAPI 2.x or 3.0.0 specification.
  • OAS validation is performed using Spectral.
  • To replicate validation in your own CI/CD pipeline, run spectral lint [spec.yaml] .spectral.yaml, where .spectral.yaml should contain the following:
    • OpenAPI spectral.yaml: Should contain extends: "spectral:oas".
    • AsyncAPI spectral.yaml: Should contain extends: "spectral:asyncapi".
• Invalid specs are permitted (with potential degraded experience), and validation_messages captures any validation issues.

API documentation is content in Markdown that you can use to provide additional information about your API.

While you are creating or editing an API document, you can also choose to publish it and make it available in your Dev Portal (assuming all parent pages are published as well). Keep the following in mind:

• The visibility of an API document is inherited from the API’s visibility and access controls.
• If a parent page is unpublished, all child pages will also be unpublished.
• If no parent pages are published, no API documentation will be visible, and the APIs list will navigate directly to generated specifications.

To create a new API document, do one of the following:

curl -X POST "https://us.api.konghq.com/v3/apis/$API_ID/documents" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "slug": "api-document",
       "status": "published",
       "title": "API Document",
       "content": "# API Document Header"
     }'

echo '
resource "konnect_api_document" "my_apidocument" {
  api_id             = "9f5061ce-78f6-4452-9108-ad7c02821fd5"
  content            = "...my_content..."
  parent_document_id = "b689d9da-f357-4687-8303-ec1c14d44e37"
  slug               = "api-document"
  status             = "published"
  title              = "API Document"
}
' >> main.tf

Page structure

The slug and parent fields create a tree of documents, and build the URL based on the slug/parent relationship. This document structure lives under a given API:

• Page name: The name used to populate the title in the front matter of the Markdown document
• Page slug: The slug used to build the URL for the document within the document structure
• Parent page: When creating a document, selecting a parent page creates a tree of relationships between the pages. This allows for effectively creating categories of documentation.

For example, if you had a document configured like the following:

• API slug: routes
• API version: v3
• Page 1: about, parent null
• Page 2: info, parent about

Based on this data, you get the following generated URLs:

• Generated URL for about page: /apis/routes-v3/docs/about
• Generated URL for info page: /apis/routes-v3/docs/about/info

You can upload an image for your API. The image is displayed as an icon for your API in any Dev Portal where the API is published. The image must be a PNG, JPG, or SVG image under 500 KB that’s no larger than 350 × 350 pixels.

To upload an API image, do the following:

1. In the Konnect sidebar, click Catalog.
2. In the Catalog sidebar, click APIs.
3. Click the API you want to add the image to.
4. From the action menu, select “Edit”.
5. Click Upload image and upload an image.

You can link to a Konnect Gateway Service v3.6+ or control plane v3.13+ to allow developers to create applications and generate credentials or API keys.

When you link an API to a Gateway, you have two options:

• Link to a single Gateway Service with the Konnect Application Auth (KAA) plugin
• Link to a control plane with the Access Control Enforcement plugin

These plugins are responsible for applying authentication and authorization on the Gateway Service or control plane. The authentication strategy that you select for the API defines how clients authenticate.

The following table can help you decide which option to pick:

Do not configure the KAA and ACE plugins on the same control plane because their overlapping interactions can be unpredictable.

The following diagram shows how the plugins manage authorization and authentication on the linked Service or control plane:

 
sequenceDiagram
    actor Client
    Client->>Kong: 
    Kong->>Auth plugins: Send request
    Auth plugins->>Auth plugins: Run configured auth plugins (like Key Auth)

    note right of Auth plugins: ACE runs after all other auth plugins.
If a prior plugin rejects the request, ACE does not run.

    Auth plugins->>ACE plugin: Forward request

    alt Request matches a defined operation
        ACE plugin->>ACE plugin: Authenticate and authorize request
using data pushed from Konnect
        ACE plugin->>Upstream: Forward authorized request
        Upstream-->>ACE plugin: Response
        ACE plugin-->>Kong: 
        Kong-->>Client: 
    else `match_policy: if_present` (no match)
        ACE plugin-->>Kong: Pass through untouched
        Kong-->>Client: 
        note right of ACE plugin: If anonymous is set, unauthenticated requests
also pass through. Use Request Termination
to block them if needed.
    else `match_policy: required` (no match)
        ACE plugin-->>Kong: Reject with 404
        Kong-->>Client: 404
    end
  

 
sequenceDiagram
    actor Client
    Client->> Kong:
    Kong->>Konnect Application Auth: Send request
    Konnect Application Auth->>Konnect Application Auth: Authenticate the request based on the auth strategy

    rect rgb(191, 223, 255)
    note right of Konnect Application Auth: OIDC Strategy
    Konnect Application Auth-->> OIDC Plugin: 
    OIDC Plugin->> IdP: Sends credentials request
    IdP ->> OIDC Plugin: return JWT token
    OIDC Plugin-->>Konnect Application Auth:
    end
    rect rgb(191, 223, 255)
    note right of Konnect Application Auth: Key Auth Strategy
    Konnect Application Auth->>Konnect Application Auth: Authenticate Api Key
    end

    Konnect Application Auth->>Konnect Application Auth: Authorize the request with the authenticated client
    Konnect Application Auth->>Kong:
    Kong->>Client:
   

If you want the Gateway Service or control plane to restrict access to the API, configure developer and application registration for your Dev Portal.

To link your API to a Gateway Service or control plane, do one of the following:

curl -X POST "https://us.api.konghq.com/v3/apis/$API_ID/implementations" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "service": {
         "control_plane_id": "'$CONTROL_PLANE_ID'",
         "id": "'$SERVICE_ID'"
       }
     }'

echo '
resource "konnect_api_implementation" "my_apiimplementation" {
  api_id = "9f5061ce-78f6-4452-9108-ad7c02821fd5"
  service_reference = {
    service = {
      control_plane_id = "9f5061ce-78f6-4452-9108-ad7c02821fd5"
      id               = "7710d5c4-d902-410b-992f-18b814155b53"
    }
  }
}
' >> main.tf

Publishing an API makes it available to one or more Dev Portals. Publishing an API in the Dev Portal involves several steps:

1. Create a new API, including the API version.
2. Upload an OpenAPI spec and/or markdown documentation (one of these is required to generate API docs).
3. If you want developers to consume the API in a self-serve way, link the API to a Gateway Service.
4. Publish the API to a Portal and apply an auth strategy. Publishing an API requires you to have the Product Publisher Konnect role.

• The visibility of pages and menus is configured independently from APIs, maximizing your flexibility.
• v3.6+ An API must be linked to a Konnect Gateway Service to be able to restrict access to your API with authentication strategies.

With the appropriate security and access and approval settings, you can publish an API securely to the appropriate audience. The following table describes various Dev Portal access control scenarios and their settings:

To publish your API, do one of the following:

curl -X PUT "https://us.api.konghq.com/v3/apis/$API_ID/publications/$PORTAL_ID" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"

echo '
resource "konnect_api_publication" "my_apipublication" {
  api_id = "9f5061ce-78f6-4452-9108-ad7c02821fd5"
  auth_strategy_ids = [
    "9c3bed4d-0322-4ea0-ba19-a4bd65d821f6"
  ]
  auto_approve_registrations = true
  portal_id                  = "f32d905a-ed33-46a3-a093-d8f536af9a8a"
  visibility                 = "private"
}
' >> main.tf

Once published, the API appears in the selected Dev Portal. If user authentication is enabled, developers can register, create applications, generate credentials, and begin using the API. If RBAC is enabled, approved developers must be assigned to a team to access the API.

Allow developers to try requests from the Dev Portal spec renderer

When you upload a spec for your API to Dev Portal, you can use the Try it! feature to allow developers to try your API right from Dev Portal. Try it! enables developers to add their authentication credentials, path parameters, and request body from the spec renderer in Dev Portal and send the request with their configuration.

The Try it! feature is enabled by default for published APIs. You can disable it by sending a PATCH request to the /v3/portals/{portalId}/customization endpoint.

You may need to enable the CORS plugin for this feature to work. Use the table below to determine the appropriate CORS configuration based on the Routes associated with your APIs:

When using OAuth2 flows, some IdPs may require including additional parameters for token requests. You can include the x-kong-client-credentials-config property in oauth2 type securitySchemes to allow users to input specific values for predefined parameters.

For example, this configuration allows spec renderer users to specify a custom audience value that is specific to their request:

components:
  securitySchemes:
    oauth2:
      type: oauth2
      x-kong-client-credentials-config:
        extraTokenRequestParameters:
          - name: audience
            label: Audience
            description: The audience of the authorization server to scope tokens to
            omitIfEmpty: true
            required: true
      flows:
        clientCredentials:
          tokenUrl: 'https://example.com/oauth/token'

Filtering published APIs in Dev Portal

You can filter and categorize published APIs on your Dev Portals with custom attributes. By assigning attributes to an API, this allows users to filter APIs in the Dev Portal sidebar. For an API, you can define one or more custom attributes, and each attribute can have one or more values. For example, if you had a Billing API, you could label it with "visibility": ["Internal"] and "platform": ["Web", "Mobile"].

For more information about how to use custom attributes for filtering APIs displayed in your Dev Portal, see the MDC documentation.