AI translation

This page was translated from German with AI. If in doubt, the German original applies.

Proto definitions¶

The .proto files are the authoritative specification of the gRPC API: the REST routes are derived from them, and the .NET SDK builds on the contract generated from them. For languages without an SDK, you generate the client stubs from these files yourself.

Download¶

State	Download
Development state (`master`, `9826472d`)	zedal-protos-latest.zip
Release `1.2.0`	zedal-protos-1.2.0.zip

A release carries the version of the NuGet package Zedal.GrpcApis, which contains the same .proto files. The development state may contain changes that are not yet part of a release.

Structure¶

The folders in the archive correspond to the proto packages. The import statements are relative to the top folder of the archive, for example import "core/v1/common_types.proto";, so use this folder as the include path.

The services are in the files *_api.proto, among others:

File	Services
`core/v1/*_api.proto`	`AuthApi`, `DocumentApi`, `DocumentTemplateApi`, `FileApi`, `CommonApi`, `MasterdataApi` and others
`bxa/diwass/v1/api/*_api.proto`	`CompanyDocumentApi`, `AuthorityDocumentApi`, `DocumentBlockApi`
`bxa/bmu/v1alpha1/api/bmu_document_api.proto`	`BmuDocumentApi`
`diwass/v1/api/*_api.proto`	`OperatorApi`, `AuthorityApi`, `RetrievalApi`, `AttachmentApi`, `SoapProxyApi`
`provider_discovery/v1/api/discovery_api.proto`	`DiscoveryApi`

The messages are in the remaining files, the document models under documents/v1/. The annotations the protos refer to (google/api, google/rpc, protoc-gen-openapiv2, openapiv3) are included in the archive. The well-known types under google/protobuf/ come with the protobuf compiler.

Generating stubs¶

Example for Python with grpcio-tools, in the folder with the extracted archive:

pip install grpcio-tools
mkdir -p generated
python -m grpc_tools.protoc -I zedal-protos-<version> \
  --python_out=generated --grpc_python_out=generated \
  $(find zedal-protos-<version> -name '*.proto')

The output folder must exist beforehand. Afterwards the modules are under generated/, for example generated/core/v1/auth_api_pb2_grpc.py with AuthApiStub. For other languages the same applies with protoc and the plugin for the language.

Endpoints, authentication and timeouts are described under gRPC.