apiproduct.proto

Package : devportal.solo.io

Top

apiproduct.proto

Table of Contents

APIProductSpec

API Products define a group of API Operations (endpoints) to be published for use by Developers. The API Product resource declares which APIs are bundled together as well as how to route to the backends serving those APIs.
API Products also define Usage Plans which are used to define access and rate limits for Identified API Consumers.

Field Type Label Description
displayInfo APIProductSpec.DisplayInfo User-facing information to display to GUI users for this API Product
publishRoutes google.protobuf.BoolValue expose Gateway Routes for the APIs published in this API Product. defaults to true.
domains []string repeated the domains that will serve this api product. domains must be unique across all API Products. These must be a valid FQDN or wildcard hostname.
Port should not be included here, instead specified on the Gateway resource in Gloo or Istio.
When using Istio, these domains must match one or more hosts inside the servers field on the Istio Gateway.
basePath string the base path that will serve this api product. endpoint matchers must be unique for a domain+basepath set. incoming requests will be rewritten to match the API WARNING: this field is currently ignored by the server.
apis []APIProductSpec.APISelector repeated the selection of APIs defined in ApiDocs which this APIProduct exposes.
defaultRoute RouteSpecifier an optional default configuration for all Operations defined in this APIProduct. Operations contained in this APIProduct will inherit this config when they do not provide their own. If no OperationConfig is defined for an Operation at any level, a route will not be exposed for the Operation.
plans []UsagePlan repeated a list of Usage Plans available for accessing this API Product. if none are specified, unlimited access will be enabled for unauthorized users.

APIProductSpec.APISelector

used to a set of Operations from a specific ApiDoc

Field Type Label Description
apiDoc common.devportal.solo.io.ObjectRef A reference to the ApiDoc defining the operations
openApi OpenAPIOperationSelector a selection of OpenAPI methods
grpc GrpcMethodSelector information specific to a grpc method

APIProductSpec.DisplayInfo

user-facing display information about this

Field Type Label Description
title string
description string
termsOfService string
contact APIProductSpec.DisplayInfo.Contact
license APIProductSpec.DisplayInfo.License
version string
image common.devportal.solo.io.DataSource The image to display in UIs for this API Product.

APIProductSpec.DisplayInfo.Contact

Field Type Label Description
name string
url string
email string

APIProductSpec.DisplayInfo.License

Field Type Label Description
name string
url string

APIProductStatus

The current status of the APIProduct. The APIProduct will be processed as soon as one or more Portals select it for publishing.

Field Type Label Description
observedGeneration int64 The observed generation of the APIProduct. When this matches the APIProduct’s metadata.generation, it indicates the status is up-to-date.
state common.devportal.solo.io.State The current state of the APIProduct.
reason string A human-readable string explaining the error, if any.
modifiedDate google.protobuf.Timestamp Most recent date the ApiDoc was updated.
usagePlans []APIProductStatus.UsagePlanStatus repeated for each Usage Plan defined on the API Product, indicates the APIKeys, if any, provisioned for the plan
openApiSchema google.protobuf.Struct the merged OpenAPI Schema for any selected OpenAPI operations
grpcDescriptors google.protobuf.Struct the merged gRPC Descriptors for any selected gRPC methods
numberOfEndpoints int32 the total number of API endpoints exposed in the published API Product
apiRoutes []APIRoute repeated an internal representation of the HTTP Routes generated for this API Product. these are translated to Gateway configuration for any enabled routes.
publishedPortals []APIProductStatus.ReferencingPortal repeated the set of Portals on which this Product is published. includes routing data about the Portals relevant to the Product.
observedLabels []APIProductStatus.ObservedLabelsEntry repeated The set of labels that are observed in the metadata.labels on the APIProduct. These labels are used to map APIProducts to Portals by the Dev Portal controller.

APIProductStatus.ObservedLabelsEntry

Field Type Label Description
key string
value string

APIProductStatus.ReferencingPortal

information about a Portal which references this APIProduct

Field Type Label Description
name string the name of the Portal
namespace string the namespace of the Portal
domains []string repeated a list of the Portal domains which currently give access to this API Product. this is required to properly configure CORS access for users of the Portal Interactive API UI.

APIProductStatus.UsagePlanStatus

Gives the Status of a Usage Plan that lives on the portal.

Field Type Label Description
name string Name of the plan
provisionedKeys []common.devportal.solo.io.ObjectRef repeated The Secrets containing the APIKeys that have been provisioned for this usage plan.

APIRoute

an API Route is a route (matcher + destination) generated from an API definition combined with a Route config. These are translated internally into Istio and Gloo routing configurations.

Field Type Label Description
operationId string the ID of the operation. this can be a gRPC method in the format “package.service.method” or an OpenAPI OperationID
method string the HTTP method of the operation
path string the full HTTP Path of the operation. if a parameter is specified (as in OpenAPI), a regex matcher will be generated.
summary string optional description of the route
route RouteSpec the resolved route config for the API Route.
usagePlans []string repeated The names of the usage plans that are authorized to access this route. If the route is imported into a Product where the UsagePlan does not exist, the route will be considered invalid.

GatewayConfig

indicates how operations will be exposed on the underlying Gateway (i.e.: Gloo or Istio)

Field Type Label Description
route RouteSpecifier Specify a route for exposing the Operation to HTTP traffic. If not provided, this will be inherited from the API Product’s default Route. Route Specifiers can also be plaed directly in the API Doc on the operation or service itself. See details on [configuring routing inside of API Docs](

/dev-portal/latest/todo ) | | usagePlans | []string | repeated | The names of the usage plans that are authorized to access this route. If the route is imported into a Product where the UsagePlan does not exist, the route will be considered invalid. |

GrpcMethodSelector

a list of references to methods in a gRPC definition

Field Type Label Description
methods []GrpcMethodSelector.GrpcMethod repeated the list of methods defined in the gRPC Schema

GrpcMethodSelector.GrpcMethod

describes an operation (RPC method) defined in a set of gRPC Descriptors

Field Type Label Description
serviceName string the name of the gRPC service serving the RPC method.
rpcName string the name of the RPC method as defined on the service.
gatewayConfig GatewayConfig Specify how to expose the method on the Gateway

OpenAPIOperationSelector

Field Type Label Description
operations []OpenAPIOperationSelector.OpenAPIOperation repeated the list of operations to select from in the OpenAPI schema

OpenAPIOperationSelector.OpenAPIOperation

describes an operation defined in an OpenAPI schema

Field Type Label Description
id string the OperationID of the operation. the same ID may not be selected more than once
gatewayConfig GatewayConfig Specify how to expose the Operation on the Gateway

UsagePlan

A UsagePlan describes a policy applied to Consumers of an API Product. Rate limits will be applied to HTTP traffic according to the plan for which the API Key was issued.

Field Type Label Description
name string Names must be unique for usage plans
displayName string User-facing display name for the plan
rateLimit UsagePlan.RateLimitPolicy The rate limits enforced for users (API Consumers) of the plan. Leave empty to allow unlimited API access for users of this plan.
authPolicy UsagePlan.AuthPolicy choose an auth policy for this plan

UsagePlan.AuthPolicy

Field Type Label Description
unauthorized UsagePlan.AuthPolicy.Unauthorized Consumers do not require authorization to use this plan. Only one Unauthorized usage plan may exist for an API Product.
apiKey UsagePlan.AuthPolicy.APIKey Consumers will authenticate using API Keys created under this usage plan.
oauth UsagePlan.AuthPolicy.OAuth Consumers will authenticate using OAuth tokens. If using OAuth, at least one OAuth scope must be provided in AllowedScopes

UsagePlan.AuthPolicy.APIKey

UsagePlan.AuthPolicy.OAuth

Field Type Label Description
allowedScopes []string repeated If using an OAuth Auth Policy, a list of Allowed Scopes must be provided here to properly authorize users authenticated with OAuth.
If an OAuth token carries one of these scopes, the client will be permitted access to the API under this Usage Plan.
Allowed Scopes must be unique (cannot overlap) across all of a Product’s Plans.

UsagePlan.AuthPolicy.Unauthorized

UsagePlan.RateLimitPolicy

a Rate Limit Policy that can be applied to request traffic from an authorized client.

Field Type Label Description
unit UsagePlan.RateLimitPolicy.Unit
requestsPerUnit uint32

UsagePlan.RateLimitPolicy.Unit

Name Number Description
UNKNOWN 0
SECOND 1
MINUTE 2
HOUR 3
DAY 4