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.

Field	Description	Validation 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.

Field	Description	Validation 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.

Field	Description	Validation 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.

Field	Description	Validation 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.

Field	Description	Validation 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.

Field	Description	Validation 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.

Field	Description	Validation 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.

Field	Description	Validation 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.

Field	Number	Description
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.