Skip to content

Self-Service API (REST) [L]

Warum?

Um empfangende Systeme automatisch über eine Schnittstelle konfigurieren zu können, soll das anlegen und Verwalten von Zustellpunkten über eine API ermöglicht werden.

Relevante Links und Bemerkungen

Squenzdiagramm: Anlegen eines neues Zustellpunktes via API

Annahme: Ein API-Client ist genau einem User zugeordnet.

Bisher

sequenceDiagram
  API-Client ->> OAuth: (B) Access Token (enthält "create:destination-id") abrufen  
  API-Client ->> SSP/Mgt-Backend: Destination-ID anlegen { name: "", submissionHost: "" } (POST)
  SSP/Mgt-Backend ->> SSP/Mgt-Backend: UUID generieren
  SSP/Mgt-Backend ->> Zustelldienst: (A) Destination-ID anlegen
  Zustelldienst ->> Zustelldienst: Destination-ID als Datenbankeintrag anlegen
  SSP/Mgt-Backend->> SSP/Mgt-Backend: Destination-ID einem User auf Basis der Client-Zugehörigkeit zuordnen
  %% SSP ->> SSP: Zustellpunkt einem Team auf Basis der Client-Zugehörigkeit zuordnen (Berechtigung setzen)
  SSP/Mgt-Backend->> OAuth: Scope ("manage:destination:...") + `aud` anlegen
  API-Client ->> OAuth: Access Token (enthält "manage:destination:...") abrufen
  API-Client ->> Zustelldienst: Zustellpunkt konfigueren (PUT) (nur möglich, wenn Destination-ID bereits existiert)
  Zustelldienst ->> Zustelldienst: Zustellpunkt als Datenbankeintrag anlegen

Neu

sequenceDiagram
  API-Client ->> OAuth: (B) Access Token (enthält scope: "...destination-management-api/create:destination", aud: "portal...") abrufen  
  API-Client ->> SSP/Mgt-Backend: Destination anlegen { name: "", submissionHost: "", destinationData... } (POST)
  SSP/Mgt-Backend ->> Zustelldienst: Request mit neuem OAuth-Token (Scope: "create:destination", aud: "submission-api-...") <br> ohne die Attribute "name" und "submissionHost" an Zustelldienst weiterleiten
  Zustelldienst ->> Zustelldienst: UUID generieren
  Zustelldienst ->> Zustelldienst: Zustellpunkt als Datenbankeintrag anlegen
  Zustelldienst ->> SSP/Mgt-Backend: Destination-ID
  SSP/Mgt-Backend ->> SSP/Mgt-Backend: Destination-Referenz inkl. "name" und "submissionHost" anlegen
  SSP/Mgt-Backend ->> SSP/Mgt-Backend: Destination-Referenz einem User auf Basis der Client-Zugehörigkeit zuordnen
  %% SSP ->> SSP: Zustellpunkt einem Team auf Basis der Client-Zugehörigkeit zuordnen (Berechtigung setzen)
  SSP/Mgt-Backend->> OAuth: Scope ("manage:destination:...") + `aud` des Zustelldienstes anlegen
  SSP/Mgt-Backend ->> API-Client: Destination-ID
  API-Client ->> OAuth: Access Token (enthält "subscribe:destination:...") abrufen
  API-Client ->> Zustelldienst: Anträge abrufen

Weitere SSP-UI-Anforderungen (verschoben auf ~"Epic::SSP-v2")

  1. ~~Im Self-Service-Portal können auch Destination-IDs dargestellt werden, die zwar schon im SSP angelegt wurden, aber noch keinen Inhalt besitzen. Wording: "nicht konfigurierter Zustellpunkt" -> ggf. Thema für ~"Epic::SSP-v2"~~
  2. ~~Für die "nicht konfigurierten Zustellpunkte" wird der Button zum Kopieren der signierten Adressierungsinformationen nicht angezeigt und es wird keine destinationSignature erzeugt. -> ggf. Button auf Detailseite verschieben -> Abstimmung mit ~"team::Frontend" / #435 (closed) #442 (closed)~~
  3. Das Self-Service-Portal stellt immer die aktuellen Informationen zu einem Zustellpunkt dar. Dazu holt sich das SSP vor der Darstellung immer die aktuellen Zustellpunkt-Informationen über die Submission API vom Zustelldienst. -> #435 (closed) #442 (closed)

Zu klären

  1. Genaue Bezeichnung der Scopes für create:destination (mit aud für SSP bzw. Zustelldienst)
    • Vorschlag: Scope für API-Clients, um beim SSP Zustellpunkte anzulegen heißt https://schema.fitko.de/fit-connect/oauth/scopes/destination-management-api/create:destination
    • Vorschlag: Scope für SSP, um beim ZSD Zustellpunkte anzulegen heißt https://schema.fitko.de/fit-connect/oauth/scopes/submission-api/create:destination bisheriger Scope create:destination wird vorerst aus Konsistenzgründen (einheitliche Scopes in Submission API) behalten.
  2. Dokumentation der Scopes in der Dokumentation API-Spezifikation
  3. Umziehen aller Manage-Destination-Endpunkte aus Submission API nach Destination-Management-API

Anpassungsbedarf (neue Version)

  • API-Clients konfigurieren, sodass diese https://schema.fitko.de/fit-connect/oauth/scopes/destination-management-api/create:destination-Scope erhalten können -> #541 (closed)
  • SSP-Endpunkt, um Zustellpunkte zu erstellen (inkl. Anlegen der Destination-Referenz in der Datenbank) und Erstellen des manage:destination:xxx-Scopes im OAuth-Client -> war: #543 (closed), ist: #581 (closed)
  • Neue Destination Management API-Spezifiakation (1 Endpunkt: POST /v1/destinations) -> #542 (closed)
  • Erweiterung Destination Management API-Spezifiakation um alle Zustellpunktverwaltungs-Endpunkte der Submission API -> #582 (closed)
  • Zustellpunktverwaltung in der Submission API-Spezifikation wird internal -> #582 (closed)
  • Erweiterung SSP-Implementierung um neue Endpunkte der Destination Management API ("Proxy") -> #582 (closed)

Durchführungsplan (vom Entwickler bei Storyplanung auszufüllen)

Edited by Marco Holz