Dev Portal APIs

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

• Automate your API catalog with Dev Portal
• 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" \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "MyAPI",
       "attributes": {
         "env": [
           "development"
         ],
         "domains": [
           "web",
           "mobile"
         ]
       }
     }'

echo '
resource "konnect_api" "my_api" {
  provider = konnect-beta
  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 your API, you can choose to keep it unversioned or version it using a free text string. This allows you to follow the versioning system of your choice:

• Semantic versioning (examples: v1, v2)
• Date-based versioning (examples: 2024-05-10, 2024-10-22)
• Custom naming scheme (example: a1b2c3-internal-xxyyzz00)

Each API is identified using the combination of name+version. For example, if your API is named My Test API and it has a version of v3, then it will be accessible via the API as my-test-api-v3 in your list of APIs. If a version isn’t specified, then name is used as the unique identifier.

To version an API, do one of the following:

 curl -X POST "https://us.api.konghq.com/v3/apis/$API_ID/versions" \
     -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" {
  provider = konnect-beta
  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\"}}}}}}"
    type    = "oas3"
  }
  version = "1.0.0"
}
' >> main.tf

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.

To upload a spec to an API, do one of the following:

 curl -X POST "https://us.api.konghq.com/v3/apis/$API_ID/versions" \
     -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" {
  provider = konnect-beta
  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\"}}}}}}"
    type    = "oas3"
  }
  version = "1.0.0"
}
' >> main.tf

API spec validation

Konnect looks for the following during spec validation:

• Specs must be valid JSON or YAML.
• Spec should be valid according to the OpenAPI 2.x or 3.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" \
     -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" {
  provider = konnect-beta
  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 link to a Konnect Gateway Service to allow developers to create applications and generate credentials or API keys. This is available to data planes running Kong Gateway 3.6 or later.

This will install the Konnect Application Auth (KAA) plugin on that Service. The KAA plugin can only be configured from the associated Dev Portal and its published APIs.

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

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

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

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

Currently, you APIs can only have a 1:1 mapping with a Gateway Service.

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" \
     -H "Authorization: Bearer $KONNECT_TOKEN"

echo '
resource "konnect_api_publication" "my_apipublication" {
  provider = konnect-beta
  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 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 must also 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:

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.