Create your APIs

First, deploy your OpenAPI apps in your clusters. Then, configure the Gloo ApiDoc custom resource so that Gloo can stitch your APIs into a schema that can be served in a developer portal frontend.

Before you begin

Install Gloo Platform Portal at version 2.4.1 or later, including the rate limiting and external auth add-ons.

Deploy OpenAPI apps

Deploy your apps with REST API services that conform to the OpenAPI specification (OAS), v2 or v3. The following four sample apps are used throughout the Portal guides to show you how you might combine multiple APIs into different API products and developer portals.

Good job! You just deployed your REST apps. Now, choose between the following options to create your Gloo ApiDocs custom resources:

• Automatic discovery with annotations: Add annotations to your apps’ services so that Gloo automatically discovers their REST APIs.
• Automatic discovery with ApiSchemaDiscovery: Create an ApiSchemaDiscovery custom resource with a URL endpoint to your API schema. Then, Gloo fetches the API schema from the URL and automatically creates an ApiDoc for you.
• Manual ApiDoc creation: Manually create a Gloo ApiDoc custom resource to describe your REST API services. Typically, you choose this option if you use external services for apps that run outside your cluster environment, such as in a virtual machine (VM).

Automatically discover REST API services

Annotate your Kubernetes services so that Gloo automatically discovers their REST API services and creates the ApiDoc resource for you. Any time that you redeploy your workloads, Gloo refetches the OpenAPI spec to update the ApiDoc for you.

If you can't annotate your services, your service does not expose the API schema along a path. To use Gloo virtual destinations, you can create an ApiSchemaDiscovery resource instead.

1. Add the following gloo.solo.io/scrape-openapi-<field> annotations to your apps’ services so that Gloo automatically discovers their REST API services.
   The Tracks app and other sample apps already have these annotations configured for you!
   • Required -source field: Add the relative path where your service exposes its OpenAPI v2 or v3 specification in YAML or JSON format. Common paths include /api/v3/openapi.json or /swagger.json. You might also provide a publicly accessible URL to the spec, such as Istio's bookinfo example: https://raw.githubusercontent.com/istio/istio/master/samples/bookinfo/swagger.yaml.
   • Optional -scheme field: Enter http or https for the protocol scheme to use when accessing the OpenAPI schema, such as if it differs from the source endpoint. The default value is http.
   • Optional port field: Enter the port to use when accessing the OpenAPI schema, such as if it differs from the source endpoint.
   • Optional -pull-attempts, -retry-delay, -use-backoff fields: You can configure these annotations for increased resiliency. For example, if your workload's container takes some time to spin up, you might adjust the retry delay or the number of pull attempts.
     • kubectl steps
     • YAML steps

     kubectl -n tracks annotate service tracks-rest-api --overwrite gloo.solo.io/scrape-openapi-source=/swagger.json
     kubectl -n tracks annotate service tracks-rest-api --overwrite gloo.solo.io/scrape-openapi-scheme="v2"
     kubectl -n tracks annotate service tracks-rest-api --overwrite gloo.solo.io/scrape-openapi-port="91234"
     kubectl -n tracks annotate service tracks-rest-api --overwrite gloo.solo.io/scrape-openapi-pull-attempts="3"
     kubectl -n tracks annotate service tracks-rest-api --overwrite gloo.solo.io/scrape-openapi-retry-delay="30s"
     kubectl -n tracks annotate service tracks-rest-api --overwrite gloo.solo.io/scrape-openapi-use-backoff="true"
     

     1. Get the configuration of your OpenAPI services. The following example checks the Tracks app.

        kubectl get svc -n tracks -o yaml > svc.yaml
        

     2. Add the following annotations. Make any adjustments to the default values that you need.

          annotations:
            gloo.solo.io/scrape-openapi-source: /swagger.json
            gloo.solo.io/scrape-openapi-scheme: "v2"
            gloo.solo.io/scrape-openapi-port: "91234"
            gloo.solo.io/scrape-openapi-retry-delay: "5s"
            gloo.solo.io/scrape-openapi-pull-attempts: "3"
            gloo.solo.io/scrape-openapi-use-backoff: "true"
        

     3. Apply the updated services.

        kubectl apply -n tracks -f svc.yaml
        

2. Verify that your ApiDocs are created.

Discover API schema from a URL

Create an ApiSchemaDiscovery custom resource so that Gloo automatically discovers your API schema. You configure the URL endpoint to fetch the OpenAPI schema from, as well as the target destination that serves the OpenAPI schema, such as a Kubernetes service or Gloo virtual destination in the same cluster.

After discovering the OpenAPI schema, the Gloo agent automatically generates an ApiDoc resource. To refresh the OpenAPI schema, you can delete and recreate the ApiSchemaDiscovery.

1. Create an ApiSchemaDiscovery custom resource. The following example:

   • Pulls an OpenAPI schema.json file from the https://example.com/tracks-schema.json URL. For https, make sure that the URL is included in the certificate that validates the HTTPS traffic.
   • Specifies that the tracks-rest-api Kubernetes service in the same cluster as the ApiSchemaDiscovery resource serves the OpenAPI schema. In multicluster scenarios, this cluster is usually the workload cluster.
   • For more configuration options such as retry, pull, and backoff settings for fetching, see the API reference docs.

   kubectl apply -f - << EOF
   apiVersion: apimanagement.gloo.solo.io/v2
   kind: ApiSchemaDiscovery
   metadata:
     name: tracks-api-schema
     namespace: tracks
   spec:
     openapi:
       fetchEndpoint:
         url: "https://example.com/tracks-schema.json"
     servedBy:
     - destinationSelector:
         kind: SERVICE
         selector:
           cluster: $CLUSTER_NAME
           name: tracks-rest-api
           namespace: tracks
   EOF
   

2. Verify that your ApiDocs are created.

Manually create an ApiDoc resource

If you don't want Gloo to automatically discover and create ApiDocs for your apps, you can manually create the ApiDoc resource. You might choose this option if you use external services for apps that run outside your cluster environment, such as in a virtual machine (VM).

1. Deploy your apps with REST API services that conform to the OpenAPI specification (OAS).

2. Get the OpenAPI schema for the apps that you deployed.

3. Create the ApiDoc custom resource to describe the OpenAPI schema of your app.

   kubectl apply -f - << EOF
   apiVersion: apimanagement.gloo.solo.io/v2
   kind: ApiDoc
   metadata:
     annotations:
       cluster.solo.io/cluster: ""
     name: customers-api-schema
     namespace: default
   spec:
     openapi:
       # The YAML- or JSON-formatted OpenAPI v2 or v3 schema string to use for your API. 
       inlineString: '{"components":"customer"}'
     servedBy:
     - destinationSelector:
       port:
         number: 8080
       selector:
         cluster: $CLUSTER_NAME
         name: app
         namespace: app
   EOF
   

   Review the following table to understand this configuration. For more information, see the API docs.

   Setting	Description
   openapi.inlineString	The YAML- or JSON-formatted OpenAPI v2 or v3 schema string to use for your API. Replace this value with your schema, such as '{ "info": { "title": "Gloo Platform Portal API", "version": "1.0.0", "description": "Review the following reference documentation for the Gloo Platform portal APIs. Use these endpoints to manage user access to both the developer portal and the API resources exposed by the portal." }, "openapi": "3.0.0", "servers": [ { "url": "https://api.gloo-platform-portal.com/v1" } ], "paths": { "/login": { "get": { "description": "Logs user into the developer portal. This is the path that should be used as the callbackPath in the ExtAuthPolicy's OIDC configuration.", "operationId": "login", "security": [ { "identityToken": [ ] } ], "responses": { "200": { "description": "Successfully logged in" } }, "summary": "Logs user into the developer portal", "tags": [ "User" ] } }'
   servedBy.destinationSelector	Specify the backing destination for your app, by label or by name. This destination matches the destinations that you later route to. Supported destinations are Kubernetes services or Gloo virtual destinations.

4. Verify that your ApiDocs are created.

Verify that your ApiDocs are created

Verify that your apps are running and that Gloo has the ApiDocs that describe their OpenAPI specs.

1. Check that your apps are running.

   kubectl get pods -A
   

2. Automatic discovery: Enable port-forwarding for one of your apps and check that the OpenAPI spec exists on the path that you included in the gloo.solo.io/scrape-openapi-source annotation on the service. The following example checks the Tracks app.

   kubectl -n tracks port-forward services/tracks-rest-api 5000:5000
   

   In your browser, open http://localhost:5000/swagger.json and verify that the OpenAPI spec exists:

   {
    "swagger": "2.0",
    "info": {
      "description": "REST API for Catstronauts to retrieve data for tracks, authors and modules.",
      "version": "1.0.0",
      "title": "Catstronauts REST API"
    },
    ...
   

3. List the ApiDocs in each app's namespace.

   kubectl get apidocs -A
   

4. Describe one of the ApiDocs, and verify that the ApiDoc has the OpenAPI spec for the service.

   kubectl describe apidocs -n tracks
   

   Example output:

   ...
   Spec:
     Openapi:
       Inline String:  {"components":{"schemas":{"Author":{"properties":{"id":{"type":"string"},"name":{"type":"string"},"photo":{"type":"string"}},"type":"object"},"Module":{"properties":{"authorId":{"type":"string"},"content":{"type":"string"}
   

Next steps

Great job! You deployed your apps and made sure that Gloo has the OpenAPI spec for each of your APIs.

Next, you can bundle your APIs together into API products.