Skip to content

DRAFT: Diskussionsgrundlage f. API v1 Migration

David Schwarzmann requested to merge api-v1-discussion-proposal into develop

Abgehakte Punkte wurden bereits diskutiert & deren Ergebnis hier dokumentiert.

Generelle Fragen

  • Terms of Service f. API fehlt noch
    • Abwärtskompatibilität
      • Kompatibel für X Monate / letzten 2 Versionen
      • Kommunikationspoltitik
    • Rate Limiting bei Abuse
    • Public API / non Public API
    • Blocken möglich?
    • Sicherheitsthemen: Reportingstelle, Zeitraum zum fixen, Geld
  • Warum nochmal ist eine dezentrales System notwendig?
    • Zentraler Dienst wird bereitgestellt und zusätzlich dazu besteht noch die Option ein eigenes System zu Hosten
    • Themenpunkt "Netzsegmentierung" ist ein "pro"
  • Weiter Stoplight? Wenn nein, was dann? => Schauen sich andere sachen an
  • Wer nutzt eigentlich Status History? Warum gibt es das?
    • Der Endpunkt muss nochmal angefasst werden, hinsichtlich Security
    • Dient als Flexibilität, damit die Onlinedienste den Vorgang der Anträge darstellen können
    • Status Historie soll langfristig durch einen Event-Log ersetzt werden
    • Status Historie ist notwendig, damit die Behörden die Verantwortlichkeiten das nachvollziehen & beweisen können
    • Status Historie soll in einem Atemzug durch die Event-Historie ersetzt werden
    • Event-Log muss in die 1.0
  • Add application document: Woher kommt die docId als Path Parameter? Ist sie schon vorher bekannt?
  • In den Metadaten stehen die Dokument-IDs drin, daher ist müssen die Docs entweder vorher oder nachher hochgeladen werden, abhängig von der Vorgehensweise
  • Bei Erstellung d. Antrags nur transportrelevante Inf. für ein Dokument
  • Doc-ID wird vom Sender vergeben und wird nur innerhalb des Antrags genutzt
  • Antragsschema/Application Schema:
    • Warum ein explizites Encoding? Sollte entfallen, da verschlüsselt? => Yes
    • Antrags Fachdaten werden wie genau versendet? Gibt gerade application/json application/xml und application/xml im FIM Format
      • Grundsätzlich wird JSON und XML als Format f. die Fachdaten genutzt
      • Das Format/Schema, in dem der verschlüsselte Antrag versendet wird ist für Consumer relevant und wird in den Metadaten hinterlegt
  • Warum die API-Endpunkte trennen?
    • Skalierbarkeit kann auch anders geschafft werden
    • Gefahr von Nano-Services
    • Gemeinsame Funktionalität bzw. Domäne
    • Application / Antrag ist ein Domänenobjekt

API Konsistenz:

  • POST beim Erstellen von neuen Ressourcen, PUT beim Aktualisieren von bestehenden Ressourcen
  • Lange Form der Identifier (docId => documentId oder docs => documents) => Nur Benennung, nicht Format

API-Struktur:

  • Anordnung + Restrukturierung der Status-Endpunkte an die semantisch passenden Stellen
    • Upload Status ist temporär und hat nichts mit dem Antragsstatus zu tun
    • Kann raus!

Evtl. Verbesserung:

  • Erstellung von 2 Endpunkten
    • /destinations/...
    • /applications/...
    • Mit Alexander abstimmen, ob es für ihn Ok ist, dass die destinationId in den Body von "create application" gelegt wird
  • Reduktion & Einschränkung auf nur tatsächlich genutzte Parameter
    • Erhöht sonst unnötigerweise Komplexität und Anzahl v. Edge Cases
    • Ist diese allumfassende Flexibilität wirklich notwendig?
    • Vorgaben für kryptografische Parameter kommen noch und wie genau das abläuft
      • x509 ist notwendig bzgl. Verifizierung
  • OAuth2 Scopes
    • Sollte destination:send nicht application:send heißen?

Open ToDos:

  • Ref logik überprüfen und korrigieren
  • Übersetzung aller Dokumentationsparameter
  • Codegen auf Basis der Gitlab-Version der API-Spec während des Maven „generate" Lifecycle-Steps
  • Diskussion: Signing / Encryption @ https://git.fitko.de/fit-connect/FIT-Connect-PoC/-/issues/58
  • Setzen aller RequestBodies auf required
  • Setzen aller relevanten Attribute in den Models auf required

Cross-cutting concerns

Observability:

  • Monitoring der API Schnittstellen
    • Wie soll das Monitoring ablaufen?
    • Welche Tools gibt es schon bzw. sind angedacht?
  • Logging:
  • Error detection:

Weiterführende Infos/dokumentationen/Links:

Edited by Jonas Gröger

Merge request reports