Navigation :

Rewrite API paths

In Gloo Portal, your APIs are bundled together into API products by using Gloo route tables. With a route table, 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

Install Gloo Platform Portal at version 2.5.5 or later, including the rate limiting and external auth add-ons.
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

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
```

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"

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"
```

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"

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.

For help creating your regex patterns, try a tool such as regex101. Keep in mind that Gloo supports expressions in the RE2 syntax. You cannot set global pattern flags like g for global or U for ungreedy. Gloo matches on each path in the OpenAPI spec of the ApiDoc.

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

Review the following table to understand this configuration. 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.

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-addons   petstore-rt-stitched-openapi-gloo-gateway-docs-mgt-gloo-mesh-gateways-gloo-gateway-docs-mgt      81m
gloo-mesh-addons   tracks-only-rt-stitched-openapi-gloo-gateway-docs-mgt-gloo-mesh-gateways-gloo-gateway-docs-mgt   25m
gloo-mesh-addons   tracks-rt-stitched-openapi-gloo-gateway-docs-mgt-gloo-mesh-gateways-gloo-gateway-docs-mgt        49m

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

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

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
```
Optional: Remove the app that backs your API, such as by deleting its namespace.
```
kubectl delete namespace tracks
```