Defining API Routes and Endpoints
1. Creating Route Definitions
| Field | Description | Example |
|---|---|---|
name | Route identifier | get-order |
paths | Match patterns | /orders/:id |
methods | Allowed HTTP verbs | [GET, HEAD] |
hosts | Host header match | api.example.com |
service | Upstream target | orders-svc |
strip_path | Remove prefix | true |
Example: Kong route
routes:
- name: get-order
service: orders-svc
paths: ["/v1/orders"]
methods: [GET, POST]
hosts: ["api.example.com"]
strip_path: true
preserve_host: false
https_redirect_status_code: 3012. Configuring Method-Specific Routes
| Method | Use | Idempotent |
|---|---|---|
| GET | Read resource | Yes |
| POST | Create / RPC | No |
| PUT | Replace | Yes |
| PATCH | Partial update | No (usually) |
| DELETE | Remove | Yes |
| OPTIONS | CORS preflight | Yes |
3. Using Path Parameters
| Syntax | Matches | Captures |
|---|---|---|
/users/:id | /users/42 | id=42 |
/users/{id} | OpenAPI style | id |
/users/:id/posts/:pid | Nested | id, pid |
/files/*path | Greedy capture | path=a/b/c |
4. Using Query Parameters
Example: Query routing
routes:
- paths: ["/search"]
methods: [GET]
headers: {}
query_string:
version: ["2"] # match ?version=2
service: search-v2| Operator | Match |
|---|---|
exact | ?env=prod |
regex | ^v\d+$ |
present | Key exists, any value |
absent | Key must not exist |
5. Using Regular Expression Patterns
| Pattern | Matches |
|---|---|
~ ^/api/v\d+/ | Versioned APIs |
~* \.(jpg|png)$ | Image extensions (case-insensitive) |
(?<ver>v\d+) | Named capture group |
^/users/(\d+)$ | Numeric ID only |
Warning: Regex routes are slower than prefix matches. Use sparingly and benchmark.
6. Setting Up Wildcard Routes (*, **)
| Pattern | Meaning |
|---|---|
/api/* | Single segment wildcard |
/api/** | Multi-segment recursive |
*.example.com | Subdomain wildcard |
/static/*filepath | Capture remainder |
7. Configuring Route Priority and Order
| Rule | Order |
|---|---|
| Exact match | 1 (highest) |
| Longest prefix | 2 |
| Regex | 3 |
| Wildcard | 4 |
Catch-all / | 5 (lowest) |
Explicit priority field | Overrides above |
8. Setting Up Catch-All Routes
Example: 404 fallback
routes:
- name: not-found
paths: ["/"]
priority: 0
service: error-service
plugins:
- name: request-termination
config:
status_code: 404
message: "Endpoint not found"| Use Case | Pattern |
|---|---|
| Default 404 | / last priority |
| Maintenance page | Match all → static response |
| SPA fallback | /* → index.html |
9. Defining Route Descriptions and Tags
| Field | Purpose |
|---|---|
description | Free-text doc |
tags | Group/filter (env:prod) |
x-internal | Hide from public docs |
deprecated | Surface sunset warnings |
10. Configuring Route-Level Timeouts
Example: Per-route timeout override
routes:
- name: long-report
paths: ["/reports/generate"]
service: reports
connect_timeout: 5000
read_timeout: 300000 # 5 min for long jobs
write_timeout: 60000| Setting | Scope | Wins |
|---|---|---|
| Service timeout | All routes | Default |
| Route timeout | One route | Overrides service |
| Plugin timeout | Specific plugin | Local only |