Rewrite API paths

In Gloo Mesh Gateway, your APIs are bundled together into API products by using Gloo route tables. With route tables, you can use Gloo’s powerful routing features to expose your APIs. These features include regular expression (regex) to find and replace the paths of your APIs. This way, you can decouple your app development from the paths that the apps are exposed on. For more information, see Redirect or rewrite requests.

Before you begin link

1. Install Gloo Platform Portal, including the rate limiting and external auth add-ons.
2. Deploy the API that you want to expose. Your API must be a REST service that conforms to the OpenAPI specification (OAS) v2 or v3. Ideally, your API has several different paths, some of which you want to rewrite. The example in this guide uses the Tracks app.

Rewrite the API path with regex matching link

1. Check that your APIs are available for use in Gloo Portal by confirming that an ApiDoc exists for your API, such as the Tracks app. If not, see the Create your APIs guide.

     kubectl get apidocs -A
     

2. Describe the OpenAPI spec of the ApiDoc to find the paths of your app. The following example command uses jq to list the paths of the Tracks API.

     # Store the OpenAPI JSON output of the Tracks API in an environment variable
   json_output=$(kubectl get apidocs -n tracks -o json | jq '.items[0].spec.openapi.inlineString | fromjson')
   
   # Extract the "path" values from the OpenAPI JSON output
   path_values=$(echo "$json_output" | jq '.paths | keys[]')
   
   # Print the extracted path values
   echo "$path_values"
     

3. Decide which paths you want to expose in the developer portal from the output of the previous step. In the example, notice that the Tracks app includes paths for tracks, authors, and modules. You can use regex matching in a route table to expose only certain paths, such as the track-related paths.

     "/author/{id}"
   "/module/{id}"
   "/track/{id}"
   "/track/{id}/modules"
   "/track/{id}/numberOfViews"
   "/tracks"
     

4. Decide on the information for your new Tracks API product to display in the end-user facing API documentation in your developer portal. At a minimum, each route table for a portal must include an apiProductId and an apiVersion. You can also include other portal metadata, as shown in the following example. For more multiple versions of your APIs, see Version your APIs. For more information about each setting, see the API docs.

     
     portalMetadata:
       apiProductId: "tracks-only"
       apiProductDisplayName: "Catstronauts Course Tracks Only"
       apiVersion: "v2"
       title: "Catstronauts REST API - Tracks Only"
       description: "REST API for Catstronauts to retrieve data for tracks. Authors and modules must be retrieved separately."
       termsOfService: "You must authenticate to use this API! And other Terms of Service."
       contact: "support@example.com"
       license: "License info, such as MIT"
       lifecycle: "Supported"
       customMetadata:
         compatibility: "None"
     

5. Create a route table to represent the new Tracks API product. The route table uses regex matching to make only track-related paths available as an API product.

     kubectl apply -f - << EOF
   apiVersion: networking.gloo.solo.io/v2
   kind: RouteTable
   metadata:
     name: tracks-only-rt
     namespace: gloo-mesh-gateways
     labels:
        portal: dev-portal
        api: tracks
   spec:
     http:
     - name: tracks-only-api
       labels:
         usagePlans: dev-portal
       matchers:
       - uri:
           regex: /track(.*)
       forwardTo:
         regexRewrite:
           pattern:
             regex: /track(.*)
           substitution: /track\1
         destinations:
         - ref:
             name: tracks-rest-api
             namespace: tracks
           port:
             number: 5000
     portalMetadata:
       apiProductId: "tracks-only"
       apiProductDisplayName: "Catstronauts Course Tracks Only"
       apiVersion: "v2"
       title: "Catstronauts REST API - Tracks Only"
       description: "REST API for Catstronauts to retrieve data for tracks. Authors and modules must be retrieved separately."
       termsOfService: "You must authenticate to use this API! And other Terms of Service."
       contact: "support@example.com"
       license: "License info, such as MIT"
       lifecycle: "Supported"
       customMetadata:
         compatibility: "None"
   EOF
     

   For more information, see the API docs.

   Setting	Description
   Namespace	Create the route table in the same namespace, or import it into the same Gloo workspace as the ingress gateway. In this example, the route table is in the same namespace as the ingress gateway, gloo-mesh-gateways.
   Labels	Include labels to help select this route table with other portal resources later. This example has two labels. The portal: dev-portal label can be used to associate this route table as part of the dev-portal collection of Gloo resources, while the api: tracks label can be used to associate this route table more specifically with the Tracks API.
   HTTP name and labels	Name your route and add a label that you can use to apply the policies of your usage plan to the route later. In this example, the tracks-api route has a usagePlans: dev-portal label.
   HTTP matchers	Define the routes to match for your API. This example uses regex to match the pattern /track(.*). This pattern matches routes with /track, and then captures the content afterwards in a group (.*). By default, Gloo matches the regex pattern for each path in the OpenAPI spec of the app’s ApiDoc. In the Tracks example, this regex pattern matches all of the track-related paths, but none of the authors or modules.
   HTTP forward to regexRewrite	To rewrite the path, set the pattern.regex to match the same expression as the matcher. Then provide the regex that you want to replace the matched path with in the substitute field. This example replaces the matched expression with /tracks followed by the contents of the capture group \1. This way, the path stays the same. For the Tracks example, you don’t want to change the path. Instead, you want to include only track-related paths, excluding others such as authors or modules.
   HTTP destinations	Select the service that exposes your API. In this example, the Tracks service is selected. This service includes tracks, authors, and modules. However, the regex matching ensures that only the tracks paths are available for this API product.
   Portal metadata	A set of key-value pairs that describe your API, which you put together in the previous step. Later, your developer portal displays this information in the end-user facing API documentation.

6. Check that your new track-only APIs are available for use in Gloo Portal by confirming that an ApiDoc exists for your API. If you do not have an ApiDoc, check the management server logs for an error such as no matching path items found for route table. Such errors indicate that the regex pattern does not match any routes for your API. Try revising the regex pattern and recreating the route table.

     kubectl get apidocs -A
     

   Example output:

     NAMESPACE          NAME                                                                                             AGE
   gloo-mesh          petstore-rt-stitched-openapi-gloo-gateway-docs-mgt-gloo-mesh-gateways-gloo-gateway-docs-mgt      81m
   gloo-mesh          tracks-only-rt-stitched-openapi-gloo-gateway-docs-mgt-gloo-mesh-gateways-gloo-gateway-docs-mgt   25m
   gloo-mesh          tracks-rt-stitched-openapi-gloo-gateway-docs-mgt-gloo-mesh-gateways-gloo-gateway-docs-mgt        49m
     

7. If you already created a frontend for the developer portal, open the portal and find your API products. The following example screenshots use the Solo sample React app.

   • From the APIs page, note that your new Tracks Only API product is available.

     

     

   • Click the Tracks Only API product, and expand the Tracks path. Note that only paths that matched your regex pattern, /track(.*), are available.

     

     

Cleanup link

You can optionally remove the resources that you set up as part of this guide.

1. Remove your Tracks Only API product by deleting the route table. The related components, such as the ApiDoc and portal config, are automatically removed for you.

     kubectl delete rt tracks-only-rt -n gloo-mesh-gateways
     

2. Optional: Remove the app that backs your API, such as by deleting its namespace.

     kubectl delete namespace tracks