Review API Release v1.0.0-alpha10

Hinweis: Wenn irgendwelche Hinweise dadurch entstand sind, dass fachliche Anforderungen nicht benannt wurden, dann rückmelden und ggf. als neue Story einplanen, wenn eine Anpassung jetzt zu aufwändig ist.

Grundsätzlicher Handlungsbedarf

Es sollte für den kommenden Sprint geklärt werden, wie externe Dokumentation innerhalb der OAS referenziert wird. An vielen Stellen ist mir aufgefallen, dass eine Referenz auf eine ausführliche OAS externe Seite sher sinnvoll gewesen wäre. (bspw. bei JWE eine Referenz auf die Krypto Dokumentationen)

Normalerweise kann man auf Ebene operation, tag oder schema mit externalDocs Objekt (https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#externalDocumentationObject) aus OAS zu einer externen Seite verlinken. Rapidoc (im Gegensatz bspw. zu ReDoc) unterstützt dieses Feature der OAS Spec nicht, sondern hat einen eigenen Mechanismus. (https://mrin9.github.io/RapiDoc/examples/links.html#overview--internal-links)

Wir sollten uns daher zeitnah entscheiden, ob wir A. den Rapidoc Ansatz spezifizieren, B. zusätzlich externalDocs Objekte spezifizieren (für lokale Doku der Nutzer) oder C. doch ein anderes Tool wie ReDoc wegen dieser Anforderung vorziehen. --> Ich kann mit allem leben, wir müssen es bloß schnell entscheiden, um die Doku effizient zu finalisieren.

Allgemeine Anpassungsbedarfe

1. Korrekte Dateibezeichner für YAML Dateien: Korrekte Bezeichner in den Endpunkt-Dateien statt Bezeichner wie "uuid.yml". Das hilft Dritten besser, die Referenzen schneller nachzuvollziehen. Bei allen anderen Dateien scheinen fachlich sinnvolle Bezeichner zu existieren.
   • https://git.fitko.de/fit-connect/FIT-Connect-PoC/-/blob/master/spec/zustelldienst.yml#L22-38
2. Fehler im Doku Rendering: Fehler in der Darstellung der Request Bodys in der generierten Dokumentation bei "Antrag einreichen" und "Anhang hinzufügen": Der Request Body fehlt, obwohl in der Spec enthalten. ​ - z.B.: https://git.fitko.de/fit-connect/FIT-Connect-PoC/-/blob/master/spec/endpoints/applications/uuid.yml#L62
3. Schemata, wenn möglich, nicht nach ihrer Verwendung benennen: Es sollte versucht werden, Datenschemata nicht nach ihrer Verwendung zu benennen, sondern durchgehend ein allgemeinen Bezeichner zu finden. z.B. statt CreateDestination --> destinationConfiguration
4. Arrays werden in der Rapidoc Doku nicht korrekt dargestellt: Bspw. in "Antrag anlegen" findet sich kein visueller Hinweis, dass attachments (wie in der Spec beschrieben) ein array sind.
5. Erläuterungen von Properties: Grundsätzlich sollten Descriptions in Properties ergänzt werden, um einen eindeutigen Umgang mit den Properties zu gewährleisten. Bspw. kann bei CreateApplication in das attachments in der Form erläutert werden, dass attachments ein array der zu übersendenden Anhänge sind und das übersendende System für alle attachments eine eindeutige UUID zu bilden hat. (Ausnahmen sind immer denkbar, wenn description bei Properties kein Mehrwert bieten)

Review: Zustellpunkte auflisten (get-all-destinations)

6. Description der Operation anpassen: "Mit diesem Request können alle selbst angelegten Zustellpunkte sowie ihre Konfigurationen angezeigt werden." Erläuterung --> Dieser Endpunkt ist nicht für sendende Systeme gedacht, die Informationen über alle Zustellpunkte abrufen wollen. Dieser Endpunkt ist nur für die empfangenen Systeme gedacht, um Informationen über alle ihre eigenen Zustellpunkte abrufen zu können. Hinweis zum Testing: Dieser Endpunkt ist nur korrekt implementiert, wenn solche Zustellpunkte ausgegeben werden, die den Ownern zugeordnet sind, deren ID im OAuth Token enthalten ist.
7. Response Objekt ist falsch: Da der Endpunkt die komplette Konfiguration ausgibt, müssen alle Daten des aktuellen Schemas "CreateDestination" ausgegeben werden.
8. Siehe Änderungen aus dem Review für create-destination

Review: Zustellpunkt anlegen (create-destination)

9. Operation Description verbessern: "Erstellung eines neuen Zustellpunktes mit der festgelegten Konfiguration zum Empfang von Anträgen".
10. Callback Description ist falsch: Formulierungsvorschlag --> "Öffentlich erreichbare Callback Adresse, um Benachrichtigungen beim Vorliegen neuer Anträge zu empfangen."
11. Offener Prüfpunkt Schlüsselinformationen: Siehe Kommentar unten.
12. Änderungen im Request Body bei den Properties für contact:
    • contact description: Kontaktinformationen eines organisatorischen Ansprechpartners für die Klärung von Problemen und Mitteilung von Änderungen / Vorfällen im Kontext des Betriebs der Infrastruktur und Anbindung von Zustellpunkten.
    • organizationName description: "Name der verantwortlichen Organisation"
    • organization als objekt mit mit Name, Adresse und optionaler Angabe der verantwortlichen Untereinheit (Im Sinne „Organization Unit“ des X.520-Standards oder vergleichbares Konzept aus Beta7. Entweder in der Description oder im Bezeichner sollte klar sein, dass es verantwortliche Untereinheit ist).
    • email description: "Dauerhaft erreichbares Funktionspostfach zur elektronischen Kommunikation"
    • Telefonnummer als Property ergänzen (passenden technischen Bezeichner hierfür prüfen), mit folgender Beschreibung: Telefonnummer des Ansprechpartners zur Klärung von Fragestellungen. Telefonnummer ist erreichbar mit
    • firstName und lastName entfernen, um die Speicherung personenbezogener zu vermeiden. (Über die oben gemachten Angaben sollte ein Klärungsprozess möglich sein. @Marco_Holz und @Andreas_Huber : Wie seht ihr das? Ich sehe kein Szenario, wo wir hier eine natürliche Person haben und nicht die Org Informationen nutzen können.)

Review: Zustellpunkt abfragen (get-destination-info)

13. OAS Tag ändern: Gehört fachlich nicht in "Destination Management" rein, weil es nicht im Destination Management genutzt wird. Fachlich korrekter Tag wäre "Application Transfer".
14. Offener Prüfpunkt Schlüsselinformationen: Siehe Kommentar unten.

Review: Zustellpunkt aktualisieren (update-destination)

15. Operation Description verbessern: "Zustellpunkt Konfiguration aktualisieren"
16. Siehe Änderungen aus dem Review für create-destination

Review: Zustellpunkt löschen (delete-destination)

17. Rückfrage zum leeren JSON Objekt: Ist das leere JSON Objekt immer noch im Tooling begründet oder könnte der Response Body komplett leer sein?

Review: Antrag anlegen (submit-application)

18. Description der Operation optimieren: "Durch diesen Endpunkt wird eine Übermittlungsvorgang angelegt und die damit verbundenen Daten übermittelt."
19. Bezeichner "announcedAttachments" fachlich inkorrekt: Hier werden Angaben zum Fachdatensatz (data) und zu den Anhängen (Attachments) gemacht, daher ist der Bezeichner verwirrend. "announcedContentStructure" wäre besser. Damit wäre der Bezeichner sprachlich passend zur contentStructure in den verschlüsselten Antragsmetadaten.
20. Description des Request Schema optimieren: "Angaben zum adressierten Endpunkt und den vorgesehenen Uploads für den Fachdatensatz und die Anhänge."

Review: Anhang hinzufügen (add-application-attachment)

21. Description der Operation korrigieren/ optimieren: "Upload des in announcedContentStructure" angekündigten Anhangs als JSON Web Encryption unter der mitgeteilten UUID."
22. Erneute Rückfrage zum leeren JSON Objekt (Siehe Frage oben): Ist das leere JSON Objekt immer noch im Tooling begründet oder könnte der Response Body komplett leer sein?

Review: Antrag einreichen (submit-application)

23. Siehe Fehler oben bzgl. der Rapidoc Doku.
24. Mediatype falsch: RequestBody ist kein application/jose, sondern application/json mit einem json Objekt, bei dem zwei JWE Objekte Base64 kodiert enthalten sind. JWE Objekte sollten in den Properties entsprechend beschrieben sein.

Review: Antrag abrufen (get-application)

25. Siehe oben Umbenennung zu announcedContentStructure
26. Schema und Example sind unterschiedlich: Bezieht sich vielleicht auf den nächsten Punkt.
27. Announced Attachments entfernen: Informationen werden hier nicht mehr benötigt, da data im Objekt schon enthalten ist bzw. die attachment Information schon vorher im Objekt vorkommen.
28. statushistory entfernen: Dem abrufenden System die statusHistory zu schicken macht fachlich wenig Sinn. Bei jedem Abruf hat es den Status 'forwarded'.

Review: Abholung des Antrags bestätigen (acknowledge-application)

29. Rückfrage: Ist die Idee hinter dem PUT, die Ressource zu überschreiben? Sind alle Bodys leer, weil wir hier noch große Änderungen durch SET zu erwarten haben?

Review: Anhang abrufen (get-application-attachment)

30. Optimierung JWE Darstellung: 1. Bezeichner fehlt. 2. In der Description könnte noch ein kleiner Hinweis zur JWE Verschlüsselung und Base64 noch rein. Perspektivisch könnte hier auch einer Referenz auf eine externe Dokumentation helfen.

changed the description

changed the description

changed the description

changed the description

changed the description

@Marco_Holz : Bitte folgenden Punkt im Datenschema prüfen:

API-Spec:

      properties:
        contact:
          $ref: '#/components/schemas/Contact'
        schemas:
          uniqueItems: true
          minItems: 1
          type: array
          description: Auflistung aller unterstützten Antragsschemata des Zustellpunktes.
          items:
            $ref: '#/components/schemas/ApplicationSchema'
        callback:
          type: string
          minLength: 1
          format: uri
          description: 'Öffentliche URL des Zustellpunktes, an den Anträge geliefert werden sollen.'
        encryptionKid:
          type: string
          maxLength: 64
          description: Öffentlicher Teil des Verschlüsselungsschlüssels der Destination. Ist im Attribut `keys` abrufbar.
        keys:
          $ref: '#/components/schemas/JWKS'

Beispiel:

{
  "encryptionKid": "my-key-id-0xfff",
  "keys": {
    "keys": [
      {
        "kty": "RSA",
        "kid": "my-key-id-0xfff"
      }
    ]
}

Ich glaube der encryptionKid muss raus. Für jeden Key gibt es einen eigenen Kid und der Kid ist sowieso Teil des JWKS. Ich wüsste aktuell nicht wofür encryptionKid gebraucht wird. (Ich habe aber die Kypto Vorgaben auch nicht im Blick)

Damit man weiss welchen Key man zur Verschlüsselung aus der Liste des JWKS nutzen soll. Da können nämlich viele Schlüssel (z.B. auch mehrere gültige Verschlüsselungsschlüssel oder aber auch Signaturschlüssel drin liegen).

Genau. Siehe #58 (closed) (Ergänzung: In der Praxis sollte hier nur ein Public Key liegen. Dieser ist auch anhand des key_ops-Attribut von den Signaturkeys abgrenzbar. Um Fehlern im Umgang mit Public Keys in der Praxis vorzubeugen, halte ich die eindeutige Referenzierung des Keys, der für die Verschlüsselung genutzt werden muss, über das Attribut encryptionKid aber für sehr sinnig.)

Generell würde ich noch anregen, das äußere keys-Attribut in publicKeys (oder jwks?) umzubenennen, um Verwirrungen bei der Implementierung von API-Clients vorzubeugen:

{
  "encryptionKid": "my-key-id-0xfff",
  "publicKeys": {
    "keys": [
      {
        "kty": "RSA",
        "kid": "my-key-id-0xfff"
      }
    ]
}

Done

changed the description

changed the description

changed the description

changed the description

changed the description

changed the description

changed the description