tapir

The T-online API Repository contains the interface definitions of t-online APIs that support the gRPC protocol. You can use these definitions with open source tools to generate client libraries, documentation and other artifacts.

T-online APIs use Protocol Buffers version 3 (proto3) as their Interface Definition Language (IDL) to define the API interface and the structure of the payload messages.

overview

guidelines

• tapir provides an IDL and RCP services stubs to access editorial content and their configuration. This allows delivering various t-online products developed by independent teams
• RPC services and proto messages are optimized for an efficient development and delivery of those products: One of our internal API guideline demands that all the content required to render a page must depend on a single API call.
• different editorial content types and product features are modeled by the same proto messages using the same concepts. This allows to keep the APIs clean and future proof. Examples:
  • articles, videos or galleries share the same message structure distinguished by a type field
  • attributes of an article are modeled as generic <string, string> maps
  • elements of an article like images, videos and their assets share the same proto messages and can be distinguished by a type field
  • enumerations are only used for stable/rarely changing lists of pre-defined values like a content type. Volatile fields like layout types are modeled as string fields.
• proto message fields and entries of maps are optional unless commented otherwise. Clients must not break if an optional field or map entry is missing.

generate code

We use the buf cli to generate code for interacting with the t-online APIs. See docs for installation instructions.

Run the following commands to generate code for java, python, node, protobuf-es (node-proto) or go:

# java and python
make generate
# node
make generate TEMPLATE=buf.gen.node.yaml
# protobuf-es
make generate TEMPLATE=buf.gen.node-proto.yaml
# go
make generate TEMPLATE=buf.gen.go.yaml

See corresponding buf.gen.*.yaml code generation configuration.

testing and quality assurance

We use the buf cli for quality assurance of our proto files:

• make lint: linting all proto files with buf lint
• make fmt: formatting all proto files with buf fmt
• make breaking: check for breaking changes against the main branch with buf breaking

These tools are configured in the buf.yaml file.

In addition, we run some basic language specific tests to verify a successful code generation for java and node.

releases

We use semantic versioning for our releases.

To create a new release runmake BUMP=[major|minor|patch] release (defaults to patch) in your clean main branch. This will create a new tag and push it to the main branch. In addition, a new release will be created in GitHub if a fine-grained personal access token is provided in the GITHUB_TOKEN environment variable.

buf schema registry

We push to the buf schema registry (BSR) automatically for each new tag. The registry provides SDKs for various languages to interact with the t-online APIs.

client libraries

In addition to the SDKs available in the buf schema registry (BSR), we generate packages hosted on GitHub for:

• java
• node
• protobuf-es

automatically for each new tag which can be integrated in your build system. Go code will be generated and tagged in go-tapir.

See our GitHub workflow for details.