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.5.3 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.

  1. Create a namespace for the Tracks app.
    kubectl create ns tracks
    
  2. Deploy the Tracks app. The following example includes the Kubernetes deployment and service for the app.
    kubectl apply -f https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-gateway/portal/tracks-api.yaml
    
  1. Create a namespace for the Users app.
    kubectl create ns users
    
  2. Deploy the Users app. The following example includes the Kubernetes deployment and service for the app.
    kubectl apply -f https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-gateway/portal/users-api.yaml
    
  1. Create a namespace for the Pets app.
    kubectl create ns pets
    
  2. Deploy the Pets app. The following example includes the Kubernetes deployment and service for the app.
    kubectl apply -f https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-gateway/portal/pets-api.yaml
    
  1. Create a namespace for the Store app.
    kubectl create ns store
    
  2. Deploy the Store app. The following example includes the Kubernetes deployment and service for the app.
    kubectl apply -f https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-gateway/portal/store-api.yaml
    

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

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 -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: "30s"
            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.

Gloo reports the status of Gloo custom resources in several places, such as in logs, when describing the object in kubectl, or when viewing the object in the Gloo UI. Unlike other Gloo custom resources, ApiDocs can be both an input and output object. For example, you can manually create an ApiDoc (input), or Gloo can automatically create an ApiDoc during discovery or translation processes (output). As such, status for ApiDocs is disabled. Because the status is disabled, you cannot review statuses for ApiDocs in kubectl. Also, you might notice ApiDocs reported as unhealthy in the Gloo UI even though the ApiDocs work. To verify that your ApiDocs are healthy, you can follow the steps in the ApiDoc guide.

  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.

When you are done with trying out Portal, you can clean up all of the resources that you created.