Defining API Routes and Endpoints
1. Creating Route Definitions
Field Description Example nameRoute identifier get-orderpathsMatch patterns /orders/:idmethodsAllowed HTTP verbs [GET, HEAD]hostsHost header match api.example.comserviceUpstream target orders-svcstrip_pathRemove 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 : 301
2. 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/42id=42/users/{id}OpenAPI style id/users/:id/posts/:pidNested id, pid/files/*pathGreedy 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=prodregex^v\d+$presentKey exists, any value absentKey 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.comSubdomain wildcard /static/*filepathCapture 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 priorityMaintenance page Match all → static response SPA fallback /* → index.html
Field Purpose descriptionFree-text doc tagsGroup/filter (env:prod) x-internalHide from public docs deprecatedSurface 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