Skip to main content
logoTetrate Service ExpressVersion: Latest

API

The differences between TSB and TSE API

Tetrate Service Express (TSE) utilizes many of the same components as the Tetrate Service Bridge(TSB) product but has the several distinctions. Go to Comparing TSE and TSB for more details.

API objects define a set of servers and endpoints that expose the business logic for an Application. APIs are attached to existing Applications to configure how the features exposed by the different services that are part of the Application can be accessed.

The format used to define APIs is based on the OpenAPI v3 spec. Users can attach OpenAPI documents to the applications, and Service Express will generate all the configuration that is needed to make the APIs available. Service Express also provides a set of custom extensions to the OpenAPI spec that can be used to further customize the APIs in those cases where the standard OpenAPI properties are not sufficient.

The following example shows how an API can be attached to an existing application:

apiversion: application.tsb.tetrate.io/v2
kind: API
metadata:
organization: tse
tenant: tse
application: example-app
name: ezample-app-api
spec:
description: An example OpenAPI based API
workloadSelector:
namespace: exampleapp
labels:
app: exampleapp-gateway
openapi: |
openapi: 3.0.0
info:
title: Sample API
description: An example API defined in an OpenAPI spec
version: 0.1.9
x-tsb-service: sample-app.sample-ns # service exposing this api
servers:
- url: http://api.example.com/v1
description: Optional server description, e.g. Main (production) server
- url: http://staging-api.example.com
paths:
/users:
get:
summary: Returns a list of users.
description: Optional extended description in CommonMark or HTML.
responses:
'200': # status code
description: A JSON array of user names
content:
application/json:
schema:
type: array
items:
type: string

API

An API configuring a set of servers and endpoints that expose the Application business logic.

FieldDescriptionValidation Rule

openapi

string
REQUIRED
The raw OpenAPI spec for this API.

string = {
  min_len: 1
}

workloadSelector

tetrateio.api.tsb.types.v2.WorkloadSelector
Optional selector to specify the gateway workloads (pod labels and Kubernetes namespace) under the application gateway group that should be configured with this gateway. There can be only one gateway for a workload selector in a namespace. If the selector is omitted, then the following default workload selector will be applied, based on the name of the Application and the API objects.

workloadSelector:
namespace: exampleapp
labels:
app: application-name
api: api-name

servers

List of tetrateio.api.tsb.gateway.v2.HttpServer
OUTPUT_ONLY
DEPRECATED: For new created APIs, the exposed servers will be available at httpServers. For APIs created before version 1.7, will still be available in this field.

List of ingress gateways servers that expose the API. Server hostnames must be unique in the system, and only one API can expose a specific hostname.

endpoints

List of tetrateio.api.tsb.application.v2.HTTPEndpoint
OUTPUT_ONLY
List of endpoints exposed by this API. This field is read-only and generated from the configured OpenAPI spec.

httpServers

List of tetrateio.api.tsb.gateway.v2.HTTP
OUTPUT_ONLY
List of gateways servers that expose the API. Server hostnames must be unique in the system, and only one API can expose a specific hostname.

ExposedBy

The exposer of an HTTPEndpoint.

FieldDescriptionValidation Rule

service

string oneof _exposer
OUTPUT_ONLY
The FQN of the service in the service registry that is exposing a concrete endpoint.

clusterGroup

tetrateio.api.tsb.application.v2.ExposedByClusters oneof _exposer
OUTPUT_ONLY
The clusters that are exposing a concrete endpoint.

ExposedByCluster

ExposedByCluster is a cluster or set of clusters identified by the labels that are exposing an endpoint.

FieldDescriptionValidation Rule

name

string
The name of the cluster exposing the endpoint. Only one of name or labels must be specified.

labels

map<string, string>
Labels associated with the cluster. Any cluster with matching labels will be selected as an exposer. Only one of name or labels must be specified.

weight

uint32
The weight for traffic to a cluster exposing the endpoint.

ExposedByClusters

ExposedByClusters represents the clusters that are exposing a concrete endpoint.

FieldDescriptionValidation Rule

clusters

List of tetrateio.api.tsb.application.v2.ExposedByCluster
The clusters that contain gateways exposing the HTTPEndpoint.

HTTPEndpoint

An HTTP Endpoint represents an individual HTTP path exposed in the API.

FieldDescriptionValidation Rule

path

string
OUTPUT_ONLY
The HTTP path of the endpoint, relative to the hostnames exposed by the API.

methods

List of string
OUTPUT_ONLY
The list of HTTP methods this endpoint supports.

hostnames

List of string
OUTPUT_ONLY
The list of hostnames where this endpoint is exposed. If omitted, the endpoint is assumed to be exposed in all hostnames defined for the API.

service

string
OUTPUT_ONLY
DEPRECATED: For new created APIs, the exposed servers will be available at httpServers. For APIs created before version 1.7, will still be available in this field. The FQN of the service in the service registry that is exposing this endpoint.

exposedBy

tetrateio.api.tsb.application.v2.ExposedBy
OUTPUT_ONLY
The exposer of this endpoint.

ConfigResource

ConfigResource represents a configuration object (group, ingress gateway, etc) that is related to an Application or API.

FieldDescriptionValidation Rule

fqn

string
OUTPUT_ONLY
The FQN of the resource this status is computed for.

expectedEtag

string
OUTPUT_ONLY
The expected etag field is used to check the if the configuration resource contents have changed. This might not be relevant for all configuration resources, so this field may not be set. If it is not set, the status will only report the presence or absence of the configuration resource, but not differences in its contents.

When this field is present, the status will also reflect changes in the contents of the configuration resource, and report it as DIRTY if there are differences.

exclusivelyOwned

bool
OUTPUT_ONLY
The exclusively owned flag indicates if the referenced configuration resource is exclusively owned by the object. Configuration resources that are exclusively owned by an object will be deleted when the object is deleted.

ResourceStatus

The ResourceStatus object provides information about the status of the configuration related to an Application or an API object.

Applications and APIs are translated into configuration objects (config groups, ingress gateways, etc). This status object reflects the status of the Application and APIs with regard to the generated configuration, and exposes any configuration mismatch. This status only reflects the status of the configuration objects in Service Express . It does not provide information about the status of the generated configuration in the final clusters.

FieldDescriptionValidation Rule

status

tetrateio.api.tsb.application.v2.Status
OUTPUT_ONLY
The aggregated configuration status for the Application/API. In the case of applications, the status will also reflect the aggregated status of the APIs attached to the application; if any of the APIs is missing / dirty, the application status will reflect that.

resources

List of tetrateio.api.tsb.application.v2.ResourceStatus.ConfigResourceStatus
OUTPUT_ONLY
List of the individual configuration resource statuses.

ConfigResourceStatus

Individual status for a configuration resource related to the Application/API.

FieldDescriptionValidation Rule

status

tetrateio.api.tsb.application.v2.Status
OUTPUT_ONLY
The configuration status for the individual configuration resource.

resource

tetrateio.api.tsb.application.v2.ConfigResource
OUTPUT_ONLY
The resource for which the status has been computed.

Status

The computed configuration status for the Application or API.

FieldNumberDescription

UNKNOWN

0

Unknown indicates that the status has not been computed.

MISSING

1

The missing status indicates that the configuration resource for the Applications or APIs do not exist.

DIRTY

2

Dirty Applications and APIs are those that have the corresponding configuration objects (config groups, ingress gateways, etc), but those objects have been directly modified or they current configuration does not match the one specified in the corresponding Application/API.

CONFIGURED

3

Configured Applications and APIs are those that have the corresponding configuration resources (config groups, ingress gateways, etc) and their configurations match the ones defined in the Application/API objects.