bobaaaaa / tapir

T-online API Repository

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 gRPC source code

To generate gRPC source code for t-online APIs you need to install protoc and gRPC on your local machine, or you can use our protoc docker image which includes all required plugins for java, node and go source code generation.

Then you can run make LANGUAGE=xxx to generate the source code for a specific language.

It's also possible to generate gRPC source code for java, node and go at once: make generate.

quality assurance

We use buf to lint our proto files and to detect breaking changes. In addition, we run some basic language specific tests to verify a successful code generation for java, node and go.

Run make check to run all checks.

client libraries

We generate packages for java and node automatically for each new tag which can be integrated in your build system. In addition, the generated go source code is tagged for usage with go modules.

release a new tapir version

To create a new release run make BUMP=[major|minor|patch] release (defaults to patch) in your clean master branch. In most cases you want to run

make BUMP=minor release

protoc docker image

We provide stroeer/protoc-dockerized including protoc and all required grpc plugins to generate source code for java, node and go. This docker image also supports generating a grpc-gateway reverse-proxy server.

precondition

To access our docker image you need a valid GitHub PAT (personal access token) and login to https://ghcr.io. You have to do this only once.

1. create (or re-use) a GitHub PAT in your GitHub settings
2. follow the login instructions via GitHub docs
3. ⚠️ login URL is https://ghcr.io. Example: cat ~/TOKEN.txt | docker login https://ghcr.io -u [GITHUB-USERNAME] --password-stdin

release

1. bump versions

   • protoc version in Makefile - this version will be used as the docker image tag
   • go dependency versions in go.mod
   • java dependency versions in build.gradle
   • node dependency versions in package.json

2. Export actor and token for the GitHub container registry

   • export GITHUB_ACTOR={yourusername}
   • export GITHUB_TOKEN={yourtoken} (needs read:packages, write:packages, delete:packages permissions)

3. build and push protoc docker image

   • make protoc-push