Proto: portal_metadata.proto

Package: common.gloo.solo.io

With Gloo Portal installed as part of Gloo Mesh Gateway, you can use route tables to bundle together individual routes into an API product. When the Portal resource selects your route table, Gloo automatically generates an OpenAPI specification for the API product, which includes all of the routes. You can use this PortalMetadata setting to customize details about your API product, such as by providing a title, description, terms of service, licensing, and lifecycle management information. After you deploy a frontend application for your portal, your end users can review the metadata in the portal to help them use your API products.

For more information, see the Bundle your APIs into API products guide, and the RouteTable API reference.

Example

This route table represents an API Product for a single API, such as the tracks app. The portalMetadata section defines the information for your Tracks API product that the end-user facing API documentation in your developer portal will display. 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.

  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"

PortalMetadata

Specifications for the portalMetadata section within the RouteTable resource.

FieldDescription
apiProductId(string)

Group APIs from multiple route tables together as an API product in the portal. For example, you might have separate route tables that route to different v1 and v2 versions of your billing services that have their own OpenAPI specs. By setting the apiProductId metadata to the same billing-api value in each route table, the /apis endpoint in the portal server returns the same apiProduct in the response. Then, these APIs are grouped together and shown as a single billing API product with multiple v1 and v2 versions in the frontend portal for your end users to discover and use.

Configuration constraints:
  • This field is required when using Gloo Portal.
  • The value cannot contain spaces.
apiProductDisplayName(string)

Give a name for the API product to display in the frontend portal. If omitted, the apiProductId value is used as the display name. If api_product_display_name is set to a different value in each route table that has the same apiProductId value, then the api_product_display_name value from the route table with the oldest creation timestamp is used.
apiVersion(string)

The version of the API in context of the API Product. You cannot have multiple apiVersion values for the same apiProductId value, and you must set apiProductId to use apiVersion. For example, if you have two route tables that both set apiProductId to billing-api, then one route table can also set apiVersion to v1 and the other to v2. However, both route tables cannot set the apiVersion to v1.

Configuration constraints: This field is required when using Gloo Portal.
title(string)

The title of the openAPI specification for this API.
description(string)

The description of the openAPI specification for this API. For rich text representation, you can use CommonMark syntax.
termsOfService(string)

The terms of service of the openAPI specification for this API.

Configuration constraints: The value must be a URL.
contact(string)

Contact information for the openAPI specification for this API.

Configuration constraints: The value must be an email address.
license(string)

The license of the openAPI specification for this API.

Note: Currently, the value must be the license name, not a URL.
lifecycle(string)

The current lifecycle stage of the API.
customMetadata(repeated PortalMetadata.CustomMetadataEntry)

Key-value pairs of any custom metadata that you want to show end users in the frontend portal for this API product. In particular, you might provide information about your API lifecycle management policies, such as phase=supported, phase=deprecated, compatibility=backwards, or other product information. Furthermore, the key-value pairs are added to the API Usage & Analytics data for incoming requests to this API product.

PortalMetadata.CustomMetadataEntry

FieldDescription
key(string)

value(string)