Navigation :

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

Tracks app
Users app
Pets app
Store app

Create a namespace for the Tracks app.
```
kubectl create ns tracks
```

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

Create a namespace for the Users app.
```
kubectl create ns users
```

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

Create a namespace for the Pets app.
```
kubectl create ns pets
```

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

Create a namespace for the Store app.
```
kubectl create ns store
```

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:

Automatic discovery: Add annotations to your apps’ services so that Gloo automatically discovers their REST APIs.
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 OpenAPI 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.

Add the following 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: gloo.solo.io/scrape-openapi-source: 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: You can configure the other 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 gloo.solo.io/scrape-openapi-source=/swagger.json --overwrite kubectl -n tracks annotate service tracks-rest-api gloo.solo.io/scrape-openapi-pull-attempts="3" --overwrite kubectl -n tracks annotate service tracks-rest-api gloo.solo.io/scrape-usage-retry-delay="30s" --overwrite kubectl -n tracks annotate service tracks-rest-api gloo.solo.io/scrape-usage-use-backoff="true" --overwrite
  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-usage-retry-delay: "5s" gloo.solo.io/scrape-usage-pull-attempts: "3" gloo.solo.io/scrape-usage-use-backoff: "true"
  3. Apply the updated services.
    kubectl apply -n tracks -f svc.yaml
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).

Deploy your apps with REST API services that conform to the OpenAPI specification (OAS).
Get the OpenAPI schema for the apps that you deployed.

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.

Verify that your ApiDocs are created.

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.

Verify that your ApiDocs are created

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

Check that your apps are running.
```
kubectl get pods -A
```
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"
 },
 ...
```
List the ApiDocs in each app's namespace.
```
kubectl get apidocs -A
```

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.