gRPC¶
Natives gRPC ist der direkte Weg auf die Plattform: Type-Safety durch generierte Stubs, Server-Streaming und die geringste Übertragungslast. Die .proto-Definitionen sind die maßgebliche Spezifikation — REST und das .NET SDK leiten sich daraus ab.
Endpunkte¶
| Umgebung | Nativ gRPC (HTTP/2) | gRPC-Web |
|---|---|---|
| Production | api.live.zedal.de |
openapi.live.zedal.de |
| Preview | api.preview.zedal.de |
openapi.preview.zedal.de |
| Test | api.test.zedal.de |
openapi.test.zedal.de |
Beide Wege führen auf dieselben Backend-Methoden. gRPC-Web läuft nicht über den nativen Host, sondern über openapi.* — dort wird das gRPC-Web-Framing übersetzt und Server-Streaming inkrementell ausgeliefert. Browser-Clients nutzen diesen Weg.
Authentifizierung¶
Dasselbe dreistufige Token-Modell wie bei REST, nur liegen die Werte in der gRPC-Metadata statt in HTTP-Headern:
provider_id gehört an jeden Aufruf, auch an den Login. Das .NET SDK setzt die Metadata selbst, sobald der Provider bekannt ist — wer direkt gegen gRPC baut, muss sie mitgeben.
Login (AuthApi/IssueRefreshToken) und Access-Beschaffung (AuthApi/RequestAccess) sind reguläre gRPC-Methoden. Der Ablauf inklusive Token-Rotation und der Rolle von DiscoveryApi/ListProvider ist bei REST → Authentifizierung beschrieben und gilt unverändert.
Dienste¶
| Dienst | Zuständigkeit |
|---|---|
AuthApi |
Login, Token, Sessions |
DocumentApi, DocumentTemplateApi |
Dokumente: Import, Export, Inbox, Parameter |
FileApi |
Akten-Operationen |
CommonApi, MasterdataApi |
Globale Parameter, Stammdaten |
CompanyDocumentApi |
DiWaSS aus Unternehmenssicht — Notification, Movement, Annex VII |
AuthorityDocumentApi |
DiWaSS aus Behördensicht — Acknowledgement, Decision, Signale |
OperatorApi, AuthorityApi |
DiWaSS-Verzeichnis: Betreiber- und Behördensuche |
RetrievalApi, AttachmentApi |
DiWaSS-Abruf und Anhänge |
BmuDocumentApi |
BMU-Begleit- und Übernahmescheine nach NachwV: anlegen, Layer anhängen, Felder setzen, Signaturstellen; siehe BMU-Anleitung |
DiscoveryApi |
Provider-Discovery |
Die vollständige Liste aller Operationen mit Signaturen steht in der REST-Referenz — sie ist aus denselben Protos erzeugt und deckungsgleich zum gRPC-Vertrag.
Streaming¶
Server-Streaming steht nativ und über gRPC-Web zur Verfügung. Über REST/JSON nicht — dieser Pfad ist unary.
Timeouts¶
Setze Deadlines nach der erwarteten Nutzlast, nicht pauschal. Aufrufe, die serverseitig an DiWaSS weitergereicht werden, brauchen deutlich mehr Zeit als reine Plattform-Operationen — konkrete Richtwerte stehen bei den DiWaSS-Guides. Ein knapper Default produziert DEADLINE_EXCEEDED, das wie ein Serverfehler aussieht, aber keiner ist.
Proto-Definitionen beziehen¶
Die .proto-Dateien stehen unter Proto-Definitionen als ZIP bereit, dort auch ein Beispiel für die Codegenerierung. Für .NET steht der generierte Vertrag als NuGet-Paket Zedal.GrpcApis bereit; das .NET SDK bringt es als Abhängigkeit mit.
Für andere Sprachen generierst du die Stubs aus den Protos selbst — oder du nutzt REST und sparst dir den Schritt.
Weiter¶
- Erste Schritte — Zugang und erster Aufruf
- Feldregeln — Wertebereiche und Serverregeln, die das Proto nicht ausdrückt
- REST/JSON — derselbe Funktionsumfang ohne Codegen