向Kong添加API失败，请求排查POST问题及解释upstream_url

Let's walk through fixing your API creation issue first, then clarify what upstream_url does in Kong.

Step 1: Diagnose the 404 Error #

Your POST requests to /apis are returning 404, which points to two likely issues:

Issue 1: Deprecated API Endpoint (Kong 2.x+) #

Kong made a breaking change in version 2.0: the /apis endpoint was removed in favor of a split Service + Route model. If you're running a newer Kong version (check with docker exec chapter11_kong_1 kong version), this endpoint no longer exists—hence the 404.

Issue 2: Invalid Request Body #

Even if you're on Kong 1.x (where /apis is valid), your JSON payload has a critical error: an empty key "" where you intended to define the backend service address. This invalid JSON will cause validation failures, and in some cases, unexpected 404s.

Quick Validation Check #

First, confirm your Kong Admin API is reachable at all:

curl http://localhost:8001/

You should get a JSON response with Kong version info and metadata. If this fails, check port mappings or Kong container health.

Step 2: Fix the API Creation Request #

For Kong 1.x (Legacy /apis Endpoint) #

Fix the empty key to use upstream_url, then resend the request:

{
  "name": "myapi",
  "hosts": "server1",
  "upstream_url": "http://chapter11_go-server_1:3000",
  "uris": ["/api/v1"],
  "strip_uri": true,
  "preserve_host": false
}

For Kong 2.x+ (Service + Route Model) #

You'll need two separate requests to create a Service (defines the backend) and a Route (defines how traffic matches to the Service):

1. Create the Service (replaces upstream_url):

curl -X POST http://localhost:8001/services \
  -H "Content-Type: application/json" \
  -d '{
    "name": "myapi-service",
    "url": "http://chapter11_go-server_1:3000"
  }'

2. Create the Route (matches traffic to the Service):

curl -X POST http://localhost:8001/services/myapi-service/routes \
  -H "Content-Type: application/json" \
  -d '{
    "hosts": ["server1"],
    "uris": ["/api/v1"],
    "strip_path": true,
    "preserve_host": false
  }'

Note: strip_uri was renamed to strip_path in Kong 2.x+.

What is upstream_url? #

• In Kong 1.x: upstream_url is the full URL of your backend service (like your go-server container) that Kong will proxy matching requests to. It tells Kong where to send traffic after it matches your API's rules (hosts, URIs, etc.).
• In Kong 2.x+: This concept was split into Services and Routes. The Service's url field serves the same purpose as upstream_url—it defines the backend target—while Routes handle traffic matching logic. This split makes configuration more flexible for complex setups (like load balancing across multiple backend instances).

Extra Check: Network Connectivity #

After fixing the API creation, ensure Kong can reach your go-server container:

docker exec chapter11_kong_1 ping chapter11_go-server_1

Since both containers are on the kong-net network, they should resolve each other's names automatically. If this fails, verify your Docker network setup.

内容的提问来源于stack exchange，提问作者Richard Rublev