Skip to main content

Kong Admin API

Introduction​

The Kong Admin API is a powerful interface that allows you to manage and configure your Kong API Gateway instance. As an essential part of Kong Administration, the Admin API provides a RESTful interface that enables developers and administrators to programmatically control all aspects of Kong's functionality.

Kong is a popular open-source API gateway that sits in front of your APIs, acting as a middleware layer for managing traffic, authentication, rate limiting, and more. The Admin API is what makes Kong truly flexible and automation-friendly.

In this tutorial, we'll explore how to work with the Kong Admin API, understand its core concepts, and learn how to perform common administrative tasks.

Getting Started with Kong Admin API​

Prerequisites​

Before diving into the Kong Admin API, make sure you have:

  • A running Kong instance
  • Basic understanding of RESTful APIs
  • cURL, Postman, or any HTTP client to make requests

Admin API Basics​

By default, the Kong Admin API listens on port 8001 on localhost. If you're running Kong in a Docker container or on a remote server, you'll need to adjust the URL accordingly.

The base URL structure for the Kong Admin API is:

http://{kong-host}:{admin-port}

For example, if Kong is running locally with default settings:

http://localhost:8001

Key Concepts​

RESTful Interface​

The Kong Admin API follows RESTful principles, using standard HTTP methods:

  • GET: Retrieve information
  • POST: Create resources
  • PATCH: Update resources
  • PUT: Create or update resources
  • DELETE: Remove resources

Response Format​

All responses from the Kong Admin API are in JSON format. Successful requests typically return an HTTP status code in the 2xx range, while errors return codes in the 4xx or 5xx range.

Here's an example of a successful response:

json
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "example-service",
      "host": "example.com",
      "port": 80,
      "path": "/api",
      "created_at": 1614728400
    }
  ],
  "next": null
}

Working with Kong Resources​

The Kong Admin API allows you to manage several key resources:

Let's explore how to manage these resources using the Admin API.

Services​

Services represent your upstream APIs or microservices. They define where Kong should proxy traffic.

Creating a Service​

bash
curl -X POST http://localhost:8001/services \
  -d "name=example-service" \
  -d "url=http://example.com/api"

Response:

json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "example-service",
  "protocol": "http",
  "host": "example.com",
  "port": 80,
  "path": "/api",
  "created_at": 1614728400,
  "updated_at": 1614728400
}

Listing All Services​

bash
curl -X GET http://localhost:8001/services

Retrieving a Specific Service​

bash
curl -X GET http://localhost:8001/services/example-service

Updating a Service​

bash
curl -X PATCH http://localhost:8001/services/example-service \
  -d "path=/newapi"

Deleting a Service​

bash
curl -X DELETE http://localhost:8001/services/example-service

Routes​

Routes define how requests to Kong are matched and routed to Services.

Creating a Route​

bash
curl -X POST http://localhost:8001/services/example-service/routes \
  -d "name=example-route" \
  -d "paths[]=/example" \
  -d "strip_path=true"

Response:

json
{
  "id": "b2c3d4e5-f6a1-7890-bcde-f12345678901",
  "name": "example-route",
  "service": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" },
  "protocols": ["http", "https"],
  "paths": ["/example"],
  "strip_path": true,
  "created_at": 1614728500,
  "updated_at": 1614728500
}

Consumers​

Consumers represent users of your API. They are typically end-users or applications that make requests to your APIs through Kong.

Creating a Consumer​

bash
curl -X POST http://localhost:8001/consumers \
  -d "username=example-user" \
  -d "custom_id=user-123"

Response:

json
{
  "id": "c3d4e5f6-a1b2-7890-cdef-123456789012",
  "username": "example-user",
  "custom_id": "user-123",
  "created_at": 1614728600
}

Plugins​

Plugins extend Kong's functionality, allowing you to add features like authentication, rate limiting, logging, and more.

Adding a Rate Limiting Plugin​

bash
curl -X POST http://localhost:8001/services/example-service/plugins \
  -d "name=rate-limiting" \
  -d "config.minute=5" \
  -d "config.policy=local"

Response:

json
{
  "id": "d4e5f6a1-b2c3-7890-defg-2345678901234",
  "name": "rate-limiting",
  "service": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" },
  "route": null,
  "consumer": null,
  "config": {
    "minute": 5,
    "policy": "local"
  },
  "enabled": true,
  "created_at": 1614728700
}

Real-World Applications​

Scenario 1: Setting Up an API Proxy with Authentication​

In this example, we'll set up a service that proxies requests to an external API and secures it with key authentication.

Step 1: Create the service

bash
curl -X POST http://localhost:8001/services \
  -d "name=weather-api" \
  -d "url=https://api.weatherservice.com/v1"

Step 2: Add a route to the service

bash
curl -X POST http://localhost:8001/services/weather-api/routes \
  -d "name=weather-route" \
  -d "paths[]=/weather" \
  -d "strip_path=true"

Step 3: Add key authentication plugin

bash
curl -X POST http://localhost:8001/services/weather-api/plugins \
  -d "name=key-auth"

Step 4: Create a consumer

bash
curl -X POST http://localhost:8001/consumers \
  -d "username=weather-app"

Step 5: Provision key credentials for the consumer

bash
curl -X POST http://localhost:8001/consumers/weather-app/key-auth \
  -d "key=your-api-key"

Now, to access the weather API through Kong, clients would need to include the API key in their requests:

bash
curl -X GET http://localhost:8000/weather/forecast \
  -H "apikey: your-api-key"

Scenario 2: Implementing Rate Limiting and Response Transformations​

This example demonstrates how to implement rate limiting and transform the response headers.

Step 1: Add rate limiting plugin to a service

bash
curl -X POST http://localhost:8001/services/example-service/plugins \
  -d "name=rate-limiting" \
  -d "config.minute=10" \
  -d "config.hour=100" \
  -d "config.policy=local"

Step 2: Add response transformer plugin

bash
curl -X POST http://localhost:8001/services/example-service/plugins \
  -d "name=response-transformer" \
  -d "config.add.headers=X-API-Version:v1" \
  -d "config.remove.headers=Server"

Advanced Usage​

Health Checks and Status​

Kong provides endpoints to check the health and status of your gateway:

bash
# Get basic status
curl -X GET http://localhost:8001/status

# Check if database is available
curl -X GET http://localhost:8001/

Bulk Operations with Admin API​

For managing multiple resources at once, you can use tools like jq and bash scripting:

bash
# Get all plugins for a service and disable them
SERVICE_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
curl -s http://localhost:8001/services/$SERVICE_ID/plugins | \
  jq -r '.data[].id' | \
  while read plugin_id; do
    curl -X PATCH http://localhost:8001/plugins/$plugin_id \
      -d "enabled=false"
  done

Using Tags for Organization​

Kong allows tagging resources for better organization:

bash
# Create a service with tags
curl -X POST http://localhost:8001/services \
  -d "name=tagged-service" \
  -d "url=http://example.com" \
  -d "tags[]=production" \
  -d "tags[]=external"

# Find all resources with a specific tag
curl -X GET http://localhost:8001/tags/production

Security Considerations​

When working with the Kong Admin API, keep these security practices in mind:

  1. Never expose the Admin API to public networks without proper security measures
  2. Use HTTPS for all Admin API communications
  3. Implement network-level security (firewalls, VPNs) to restrict access
  4. Consider using Kong Enterprise RBAC for fine-grained access control
  5. Audit Admin API actions for tracking changes

For production environments, configure a separate listener for the Admin API:

admin_listen = 127.0.0.1:8001 ssl

Troubleshooting​

Common Error Codes​

  • 400 Bad Request: Malformed request syntax
  • 404 Not Found: Resource doesn't exist
  • 409 Conflict: Resource already exists
  • 500 Internal Server Error: Something went wrong in Kong

Logging​

To troubleshoot issues, increase the log level in your Kong configuration:

log_level = debug

Then check the Kong error logs:

bash
tail -f /usr/local/kong/logs/error.log

Summary​

The Kong Admin API is a powerful tool for managing your API gateway. In this tutorial, we've covered:

  • Basic concepts and interaction with the Admin API
  • Managing core Kong resources (Services, Routes, Consumers, Plugins)
  • Real-world application scenarios
  • Advanced usage patterns
  • Security considerations and troubleshooting

By leveraging the Kong Admin API, you can automate your API gateway management, integrate Kong with your CI/CD pipelines, and build custom administrative interfaces tailored to your organization's needs.

Additional Resources​

  • Practice implementing various authentication mechanisms (JWT, OAuth2)
  • Try setting up a full API management solution with rate limiting, analytics, and caching
  • Experiment with declarative configuration using Kong's DB-less mode
  • Explore Kong's plugin development to extend functionality

Exercises​

  1. Create a service with multiple routes pointing to different paths on the same backend
  2. Implement a plugin that logs all requests to a specific service
  3. Set up a consumer with rate limiting that differs from the global rate limits
  4. Write a simple script that backs up all Kong configuration using the Admin API
  5. Configure a plugin that adds CORS headers to responses

By mastering the Kong Admin API, you'll be well-equipped to manage your API gateway efficiently and integrate it seamlessly into your development workflow.


If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)