See what makes Kong the fastest, most-adopted API gateway
Check out the latest Kong feature releases and updates
Single platform for SaaS end-to-end connectivity
Enterprise service mesh based on Kuma and Envoy
Collaborative API design platform
How to Scale High-Performance APIs and Microservices
Call for speakers & sponsors, Kong API Summit 2023!
2 MIN READ
A common requirement for API gateways is to rewrite the published URL to a different URL for the upstream service’s endpoint. For example, due to legacy reasons, your upstream endpoint may have a base URI like /api/oilers/. However, you want your publicly accessible API endpoint to now be named /titans/api.
Before you start, make sure you have Kong Enterprise installed, if you haven’t already.
Get Started Learn More
When you configure a route with a path, the part of the URI after the path will automatically be appended to the path value of the upstream service. In this example, we’ll use httpbin.org/anything as our mock service and HTTPie as our command-line client.
Create a service with path /anything/api/oilers:
http POST :8001/services name=runandshoot4ever host=httpbin.org path=/anything/api/oilers
Create a route with path /titans/api:
http POST :8001/services/runandshoot4ever/routes name=tannehill paths:='["/titans/api"]'
Make an API call to /titans/api:
http :8000/titans/api/players/search\?q=henry
Response (see how the URL is translated with a new base path of /anything/api/oilers):
{ "args": { "q": "henry" }, "data": "", "files": {}, "form": {}, "headers": { "Accept": "*/*", "Accept-Encoding": "gzip, deflate", "Host": "httpbin.org", "User-Agent": "HTTPie/2.0.0", "X-Forwarded-Host": "localhost" }, "json": null, "method": "GET", "origin": "172.23.0.1, 74.66.140.21, 172.23.0.1", "url": "https://konghq.com/anything/api/oilers/players/search?q=henry" }
Kong can also handle more complex URL rewriting cases by using regex capture groups in our route path and the Request Transformer Advanced plugin (bundled with Kong Enterprise). Instead of simply replacing the base URI from /api/oilers to /titans/api, our requirement is to replace /api/<function>/oilers to /titans/api/<function>.
/api/oilers
/titans/api
/api/<function>/oilers
/titans/api/<function>
Create a new service:
http POST :8001/services name=warrenmoon4ever host=httpbin.org
Next, we must configure a route to capture the parts of the URI string past that need to be preserved. Kong supports specifying regex capture groups in the paths config parameter, which can be referenced by plugins: https://docs.konghq.com/1.4.x/proxy/#capturing-groups
In our URL rewriting example, we need to set the paths parameter of our route to parse out the function name and capture the rest of the path separately.
Create a route with paths with capturing groups:
http POST :8001/services/warrenmoon4ever/routes name=mariotta paths:='["/titans/api/(?<function>\\\S+?)/(?<path>\\\S+)"]'
Configure Transform Using the Request Transformer Plugin
The next step is to configure the Request Transformer Advanced plugin on the route. Using our example, we need to set the config.replace.uri parameter to inject the function name in between /api and /oilers, then append the rest of the URI. Create a plugin configuration on the route (replace route ID value with the actual ID from the route create above):
/api
/oilers
http --form POST :8001/routes/02e1ca00-be63-4f21-80bb-b8d5189525e3/plugins name=request-transformer-advanced config.replace.uri="/anything/api/\$(uri_captures['function'])/oilers/\$(uri_captures['path'])"
Now, when we make a request to /titans/api/search/players?q=henry, the request will be translated to /api/search/oilers/players?q=henry.
/titans/api/search/players?q=henry
/api/search/oilers/players?q=henry
http :8000/titans/api/search/players\?q=henry
Response (see how the URL is translated):
{ "args": { "q": "henry" }, "data": "", "files": {}, "form": {}, "headers": { "Accept": "*/*", "Accept-Encoding": "gzip, deflate", "Host": "httpbin.org", "User-Agent": "HTTPie/2.0.0", "X-Forwarded-Host": "localhost" }, "json": null, "method": "GET", "origin": "172.23.0.1, 74.66.140.21, 172.23.0.1", "url": "https://konghq.com/anything/api/search/oilers/players?q=henry" }
This is just scratching the surface of the powerful capabilities Kong offers for helping enterprises manage APIs. Learn more at konghq.com!
Share Post
Learn more about the Kong Enterprise Service Control Platform
Request a Demo
Learn how to make your API strategy a competitive advantage.