Callback um Destination-ID ergänzen [S]

Warum?

Vom Land Hessen wurde folgender Vorschlag / Wunsch geäußert:

In dem Callback, der vom Subscriber für eine Destination angelegt wird, soll im Payload den Callbacks eine Referenz auf die Destination, für die Submissions vorliegen, damit der Client weiß, für welche Destination der Client diese Submissions abrufen muss.

Sofern eine Callback-Adresse für mehrere Destinations genutzt wird, ist es hilfreich die Destination-ID im Callback zu erfahren. Auch der Sender benötigt zur Verifikation der Empfangsbestätigung die Destination-ID um den Schlüssel laden zu können.

Daher sollten die Callbacks um die Case-ID und Destination-ID ergänzt werden.

Hinweis: Das obsolete Array submissionIds sollte mit einer kommenden Major-Version entfernt werden.

Relevante Links und Bemerkungen

Vorschlag für Payload:

Vorschlag A:

"destinations": [{ "destinationId": "xxx", "submissionIds": ["..."] }]

Vorschlag B:

"destinations": { "{destinationId}": { "submissionids": ["..."] } }

Vorschlag C (Hinweis von Alex: Hab mir mal den konkreten Payload hergenommen, um mein Vorschlag verdeutlichen. Würde auf Annahme basieren, dass pro Destination ein Callback rausgeht)

{
  "CallbackNewSubmissions": {
    "title": "Callback",
    "description": "Callback, der über abholbereite Einreichungen informiert.",
    "type": "object",
    "properties": {
      "type": {
        "title": "Art des Callbacks",
        "description": "Es liegen neue Einreichungen vor",
        "type": "string",
        "enum": [
          "https://schema.fitko.de/fit-connect/submission-api/callbacks/new-submissions"
        ]
      },
      "destinationId": {
        "title": "Destination-ID",
        "description": "Destination-ID, für die Submissions vorliegen",
        "type": "string",
      },
      "submissionIds": {
        "title": "Liste abholbereiter Einreichungen",
        "description": "Liste von `submissionId`s aller Einreichungen, die zur Abholung bereitstehen",
        "type": "array",
        "minItems": 1,
        "items": null
      }
    }
  }
}

Vorschlag D: Array submissions analog dem Endpunkt GET /v1/submissions ergänzen.

{
  "type": "https://schema.fitko.de/fit-connect/submission-api/callbacks/new-submissions",
  "submissionIds": [
    "17db365f-fc60-4000-8cba-95d5f7d6d201"
  ],
  "submissions": [
    {
      "destinationId": "879ee109-a690-4db8-ab32-424284184d7d",
      "submissionId": "17db365f-fc60-4000-8cba-95d5f7d6d201",
      "caseId": "e89e107e-ed79-40e6-ad34-4e770f9df261"
    }
  ]
}

Entscheidung: Vorschlag D wird umgesetzt.

Akzeptanzkriterien

1. Der Sender-Callback enthält das Array submissions
2. Der Subscriber-Callback enthält das Array submissions
3. API-Änderungen ist für Clients abwärtskompatibel
4. Das submissionIds-Array wurde als deprecated markiert.
5. Die Version der API-Spezifikation wurde um ein Minor-Release erhöht.
6. Die Änderungen der Callbacks wurden im Changelog und in der Dokumentation beschrieben.
7. In der Dokumentation findet sich ein Hinweis auf das submissionIds-Array (deprecated).
8. Es existiert ein Folgeissue zum Entfernen des submissionIds-Array in der nächsten ~major -Version (#573)

Durchführungsplan

• ...
• ...
• ...