Package APIs with Dev Portal

Uses: Dev Portal Kong Gateway Catalog deck

Incompatible with

on-prem

Prerequisites

Kong Konnect

This is a Konnect tutorial and requires a Konnect personal access token.

Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.
Export your token to an environment variable:
```
 export KONNECT_TOKEN='YOUR_KONNECT_PAT'
```
Copied!
Run the quickstart script to automatically provision a Control Plane and Data Plane, and configure your environment:
```
 curl -Ls https://get.konghq.com/quickstart | bash -s -- -k $KONNECT_TOKEN --deck-output
```
Copied!
This sets up a Konnect Control Plane named quickstart, provisions a local Data Plane, and prints out the following environment variable exports:
```
 export DECK_KONNECT_TOKEN=$KONNECT_TOKEN
 export DECK_KONNECT_CONTROL_PLANE_NAME=quickstart
 export KONNECT_CONTROL_PLANE_URL=https://us.api.konghq.com
 export KONNECT_PROXY_URL='http://localhost:8000'
```
Copied!
Copy and paste these into your terminal to configure your session.

decK v1.43+

decK is a CLI tool for managing Kong Gateway declaratively with state files. To complete this tutorial, install decK version 1.43 or later.

This guide uses deck gateway apply, which directly applies entity configuration to your Gateway instance. We recommend upgrading your decK installation to take advantage of this tool.

You can check your current decK version with deck version.

Konnect roles

To recover create API packages, you need the following roles:

Editor role for APIs
Publisher role for the API and API package
API Creator

Dev Portal

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:

In the Konnect sidebar, click Dev Portal.
Click New portal.
Enter a name for your Dev Portal.
Click Create and continue.
Customize your Dev Portal’s appearance.
Click Save.

Dev Portal APIs

To complete this guide, you’ll need an API in Catalog:

In the Konnect sidebar, click Catalog.
Click New API.
In the API name field, enter MyAPI.
Click Create.

Required entities

For this tutorial, you’ll need Kong Gateway entities, like Gateway Services and Routes, pre-configured. These entities are essential for Kong Gateway to function but installing them isn’t the focus of this guide.

Run the following command:

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 -

Copied!

To learn more about entities, you can read our entities documentation.

API specification

To complete this guide, you’ll need an API specification that matches the Route you created. Catalog uses the spec to add operations to your API package.

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

Copied!

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 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.

In the Konnect sidebar, click Catalog.
Click MyAPI.
Click the Gateway tab.
Click Link gateway.
From the Control plane dropdown menu, select “quickstart”.
Select Link to a control plane.
In the Add the Access Control and Enforcement plugin settings, click Add plugin.
Click Link gateway.
Click the API Specification tab.
Click Upload Spec.
Click Select file.
Select example-api-spec.yaml.
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.

In the Konnect sidebar, click Catalog.
Click the API packages tab.
Click Create API package.
In the API package name field, enter Company package.
Enable the Package rate limit.
For the rate limit, enter 5 and select “Minute”.
In the API operations settings, click Add operations from APIs.
In the Add API operations pane, click MyAPI
For GET /anything, click Add.
For PUT /anything, click Add.
For POST /anything, click Add.
Exit the Add API operations pane.
Click Create API package.
Click the Specifications tab.
Click Generate spec from operations.
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.

In the Konnect sidebar, click Catalog.
Click the API packages tab.
Click Company package.
Click Publish API.
From the Portal dropdown menu, select your Dev Portal.
From the Authentication strategy dropdown menu, select “Disabled”.
Click Public.
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 in the Konnect UI.

Cleanup

Clean up Konnect environment

If you created a new control plane and want to conserve your free trial credits or avoid unnecessary charges, delete the new control plane used in this tutorial.