Create API products
Bundle your APIs into API products that you later render in a developer portal.
API products might represent an entire product with many APIs, such as a pet store, or a large feature within the product that you want to treat separately, such as a checkout cart.
Before you begin
Create ApiDocs, which includes prerequisite steps to install Gloo Portal and to deploy OpenAPI services.
About API products
API products are what your users find and use in your developer portal. The API products might represent an entire product with many APIs, such as a pet store, or a large feature within the product that you want to treat separately, such as a checkout cart. Each API product might represent a particular version of your API.
API products target the route that the backing app is available on. This way, you have greater flexibility in how you structure your API products. To bundle your APIs into an API product, you use a Gloo RouteTable custom resource.
By using a Gloo route table, you can automatically add apps via Kubernetes labels or specify them at more fine-grained levels. You also get more advanced networking control, such as matching, redirect, rewrite, direct response, and forwarding actions. This way, you can set up complex rules for how your API products behave under different circumstances.
Choose the API product strategy that’s right for your developer portal.
- One API product per developer portal: For smaller or test use cases, you might just have one API product that you want to expose in a developer portal. In this case, you can create just one route table to represent that API product. See Bundle your APIs into an API product.
- Multiple API products per developer portal: For many use cases, your developer portal exposes several API products. To support this setup, see Create a domain-level route table for multiple API products. This approach uses route delegation.
- API versioning and lifecycle management: Many times, you might have multiple versions of an API that you want to expose to end-users. With Gloo’s flexible approach to portal metadata, you can provide support phases, compatibility, usage plans, terms of service, licensing, and other lifecycle management information for each API version. Then, you can bundle multiple API versions into a single API product. For more information, see Version your API products.
The API products are exposed through the ingress gateway that you set up. Your end users can access these API products securely via the ingress gateway by logging into the developer portal frontend that you deploy later.
With the examples in this guide, you can build a flexible API product setup as shown in the following diagram.
- The APIs are the apps that you previously deployed, and represent the destinations that you can route requests to. Each app has a corresponding Gloo ApiDoc that defines the OpenAPI spec.
- The API products include the routing rules to the backing API services.
- The Tracks API product represents a single microservice, the
tracks
API. - The Petstore API product represents three microservices, the
pets
,store
, andusers
APIs. Gloo can stitch together these services into a single schema to bundle and share these APIs as a single API product in the developer portal.
- The Tracks API product represents a single microservice, the
- You create more routing rules for the host domain,
api.example.com
, that you want to use for all your API products. Requests to this host domain are delegated to the routes of the Tracks and Petstore API products. - The gateway routes ingress requests from your end users along the
api.example.com
host to the matching route for the APIs in each API product.
Create API products
The following steps set up the scenario described in the About API products section. This setup includes several API products that are exposed under the same host domain. You can adapt these steps to your particular requirements, such as creating more API products, configuring several different host domains, or replacing the HTTP gateway with an HTTPS gateway.
Step 1: Bundle your APIs into an API product
Configure the portal metadata and routing rules for the apps that you previously deployed. This way, Gloo knows which backing APIs to use to serve information for requests along particular paths.
The following steps create two API products:
- The Tracks API product represents a single microservice, the
tracks
API. - The Petstore API product represents three microservices, the
pets
,store
, andusers
APIs. Gloo can stitch together these services into a single schema to bundle and share these APIs as a single API product in the developer portal.
Decide on the information for your 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 anapiVersion
. 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" apiProductDisplayName: "Catstronauts Course Tracks" apiVersion: "v1" title: "Catstronauts REST API" description: "REST API for Catstronauts to retrieve data for tracks, authors and modules." 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 an API Product for a single API, such as your
tracks
app.kubectl apply -f - << EOF apiVersion: networking.gloo.solo.io/v2 kind: RouteTable metadata: name: tracks-rt namespace: gloo-mesh-gateways labels: portal: dev-portal api: tracks spec: http: - name: tracks-api labels: usagePlans: dev-portal matchers: - uri: prefix: / forwardTo: pathRewrite: / destinations: - ref: name: tracks-rest-api namespace: tracks port: number: 5000 portalMetadata: apiProductId: "tracks" apiProductDisplayName: "Catstronauts Course Tracks" apiVersion: "v1" title: "Catstronauts REST API" description: "REST API for Catstronauts to retrieve data for tracks, authors and modules." 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 thedev-portal
collection of Gloo resources, while theapi: 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 ausagePlans: dev-portal
label.HTTP matchers and forwardTo
for the routeFor each app that you want to expose APIs for, define the route matchers
that you want the APIs to be available on. This example defines the/
route for thetracks-rest-api
. Then, these routes are available on the matching host, such asapi.example.com/
.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. Decide on the information for your Pet Store API product, which is a collection of several microservices that you previously deployed. Later, your developer portal displays this information in the end-user facing API documentation. At a minimum, each route table for a portal must include an
apiProductId
and anapiVersion
. You can also include other portal metadata, as shown in the following example. For more information, see the API docs.portalMetadata: apiProductId: "petstore" apiProductDisplayName: "Pet Store" apiVersion: "v1" title: "Pet Store REST API" description: "Totally awesome API for all things pets!" 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 that represents the Pet Store API product for your
pets
,users
, andstore
API microservices.kubectl apply -f - << EOF apiVersion: networking.gloo.solo.io/v2 kind: RouteTable metadata: name: petstore-rt namespace: gloo-mesh-gateways labels: portal: dev-portal api: petstore spec: http: - name: pets-api labels: usagePlans: dev-portal matchers: - uri: prefix: /pet forwardTo: destinations: - ref: name: pets-rest-api namespace: pets port: number: 5000 - name: users-api labels: usagePlans: dev-portal matchers: - uri: prefix: /user forwardTo: destinations: - ref: name: users-rest-api namespace: users port: number: 5000 - name: store-api labels: usagePlans: dev-portal matchers: - uri: prefix: /store forwardTo: destinations: - ref: name: store-rest-api namespace: store port: number: 5000 portalMetadata: apiProductId: "petstore" apiProductDisplayName: "Pet Store" apiVersion: "v1" title: "Pet Store REST API" description: "Totally awesome API for all things pets!" 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 description from the previous step and the API docs.
Setting Description 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, each route has a usagePlans: dev-portal
label.HTTP matchers and forwardTo
for the routeFor each app that you want to expose APIs for, define the route matchers
that you want the APIs to be available on. This example defines three routes:/pet
,/user
, and/store
. These routes correspond to three APIs that you previously deployed, which Gloo can then stitch together into a single schema to build the Petstore API product. Then, these routes are available on the matching host, such asapi.example.com/pet
,api.example.com/users
, orapi.example.com/store
.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. To configure the domain that you want your API products exposed on, continue to the next step.
Step 2: Create a domain-level route table for multiple API products
For many use cases, your developer portal exposes several API products. To support this setup, you can create one overarching route table for the domain of your developer portal. Then, you can delegate matching routes along certain API paths to other route tables that represent that API product.
This way, you have one main route table for the domain that you can use to expose all of the API products that it includes, such as when you create a usage plan. You can easily add more API products by delegating to more route tables. You also still keep the flexibility to apply usage plans to the particular API product’s route tables within the overarching domain’s route table, for more granular control.
Create individual route tables for each API product that you want to expose.
Create a route table for the domain that you want your API products to be exposed on. This route table delegates the routing rules for matching HTTP routes to the route tables that you previously created. Note that the following example does not set any portal metadata, because that information is set per API product in the delegated route tables.
If you only want a single route table for one API product, just add the hosts and virtual gateway fields from the following spec example to each API product’s route table.kubectl apply -f - << EOF apiVersion: networking.gloo.solo.io/v2 kind: RouteTable metadata: name: api-example-com-rt namespace: gloo-mesh-gateways spec: hosts: - api.example.com virtualGateways: - name: istio-ingressgateway namespace: gloo-mesh-gateways http: - matchers: - uri: prefix: /trackapi delegate: routeTables: - labels: api: tracks - matchers: - uri: prefix: /petstore delegate: routeTables: - labels: api: petstore 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
.Hosts Add the host domains that you want the API products to be exposed on, such as api.example.com
.Virtual gateway Select the ingress gateway with the host that you want to use to expose your apps’ APIs. In this example, the default ingress gateway is selected. HTTP matchers and delegations For each API product that you want to expose on the host domain, set up matchers and delegated route tables. In this example, requests that match /trackapi
are delegated to the Tracks route table. Requests that match/petstore
are delegated to the Petstore route table.To create the virtual gateway for the domain that you want your API products to be exposed on, continue to the next step.
Step 3: Create the gateway for your domain
To expose your API products, configure the ingress gateway to listen on a host and forward requests to the route tables.
The following example configures a simple HTTP gateway. For more examples such as HTTPS/TLS, see Configure gateway listeners.
Create individual route tables for each API product that you want to expose.
Optional: Create a domain-level route table if you want to expose several API products on the same domain.
Create a virtual gateway for the host domain that you want to expose your API products on.
kubectl apply -f - << EOF apiVersion: networking.gloo.solo.io/v2 kind: VirtualGateway metadata: name: istio-ingressgateway namespace: gloo-mesh-gateways spec: listeners: - port: number: 80 http: {} allowedRouteTables: - host: api.example.com workloads: - selector: labels: istio: ingressgateway cluster: $CLUSTER_NAME EOF
Review the following table to understand this configuration. For more information, see the API docs.
Setting Description Listener’s allowed route tables Add the host domain that matches the route table for the API products that you want to expose. In this example, the api.example.com
matches the host in the domain-level route table that you created to expose together your two API products, Tracks and Petstore.To verify your setup, continue to the next step.
Step 4: Verify your setup
You can use the Gloo UI and the terminal to verify your API product routing setup.
Gloo UI
Review the stitched API schemas for your API products in the Gloo UI.
- Launch the Gloo UI.
meshctl dashboard
- From the menu, navigate to the APIs > API Registry page and verify that you have two API products for both of the route tables that you created,
petstore-rt
andtracks-rt
. - Click one of the API products and verify that you can see the following information:
- The API Schema that describes your app’s REST APIs. You can also click View OpenAPI to see the stitched schema of the API product in JSON format.
- The Applied to Destinations shows the backing destinations of all of the apps that are included in the API product.
- Note that the Portals are not shown yet, because you have not created the Portal resource.
Terminal
Verify that you can access your APIs through the ingress gateway on the host domain that you configured.
Get the external address of your ingress gateway. The steps vary depending on the type of load balancer that backs the ingress gateway.
export INGRESS_GW_ADDRESS=$(kubectl get svc -n gloo-mesh-gateways istio-ingressgateway -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}") echo $INGRESS_GW_ADDRESS
Note: Depending on your environment, you might see
<pending>
instead of an external IP address. For example, if you are testing locally in kind or minikube, or if you have insufficient permissions in your cloud platform, you can instead port-forward the service port of the ingress gateway:kubectl -n gloo-mesh-gateways port-forward deploy/istio-ingressgateway-1-20 8081
- In your terminal, send a curl request to both of the API products that you set up. Note that the routes are not yet secured. You secure the routes with rate limiting and external auth policies later as part of your portal’s usage plan.