changelog.md

Changelog

Das Format dieser Datei basiert auf Keep a Changelog.

2021-11-17

Zustelldienst 1.0.2

• Bugfix: Es wurde der Inhalt des type Felds gefixt, der bei der Callback Übermittelung für einen Zustellpunkt verwendet wird. (Story)
• Bugfix: Es wurde der Ort der POST events api korrekt von POST /v1/submissions/{submissionId} nach POST /v1/cases/{caseId} verlegt. (Story)

2021-11-15

API Spezifikation 1.0.3

• Der Wert created für den Status wurde aus dem PATCH-Endpunkt entfernt. (Bug)

Die Version 1.0.2 wurde zurückgezogen und durch 1.0.3 ersetzt. Version 1.0.3 ist gleichwertig zu 1.0.1

2021-11-11

API Spezifikation 1.0.1

• Die Callback URIs wurden korrigiert, so dass sie jetzt die submission-api enthalten.

2021-11-10

Metadata Schema 1.0.0

• Version 1.0.0 wurde released

Self Service Portal 1.0.1

• Die auswählbare unterstütze Metadaten Version 0.9.6 bei Zustellpunkten wurde deprecated und entfernt. Sie wird durch die neu releaste Version 1.0.0 ersetzt. (Story)

Zustelldienst 1.0.1

• Die auswählbare unterstütze Metadaten Version 0.9.6 bei Zustellpunkten wurde deprecated und entfernt. Sie wird durch die neu releaste Version 1.0.0 ersetzt. Alle bestenden Zustellpunkte werden automatisch von Version 0.9.6 auf 1.0.0 migriert. (Story)
• Bugfix: Es wurde gefixt, dass bei einer erfolgreichen Einreichung nicht mehr der Sender, sondern der Empfänger über den Callback benachrichtig wird. (Story)

[1.0.0] - 2021-11-05

:::caution Diese Version beinhaltet breaking changes :::

Allgemein

• Reduktion der Verarbeitung von personenbezogenen Daten
• Daten einer Einreichung müssen nun Ende-zu-Ende verschlüsselt übertragen werden
• API-Endpunktstruktur hat sich verändert, um
  • die Pfade einfacher und kürzer zu gestalten
  • und nur Parameter zu erfassen, die auch benötigt werden

Destinations

Der Aufbau & Umfang von Destination-Objekten hat sich geändert:

• Das Attribut publicOrganization entfällt, weil
  • nur Kontaktinformationen für den Fall von technischen Problemen erfasst und hierbei so wenig Informationen wie möglich gespeichert werden sollen.
  • Der Name der Organisation ist als Attribut für eine bessere Zuordnung zu contactInformation unter legalName gewandert.
• Das Attribut technicalContact wird umbenannt zu contactInformation und inhaltlich wie im Beispiel unten geändert
• Die Attribute callback und callbackURI wurden zusammengeführt,
  • um die Struktur flacher zu gestalten,
  • und weil neben callbackURI keine anderen Attribute angeordnet sind.
• Im Attribut submissionSchemas entfällt das Attribut encoding,
  • da ab Version 1 jede Kommunikation Ende-zu-Ende verschlüsselt sein muss.
• Das Attribut publicKey wurde umbenannt zu encryptionKid. Weiterhin wurde ein Feld keys eingefügt.
  • encryptionKid: Die KeyId des Schlüssels der zur Verschlüsselung der an einen Zustellpunkt gesendeten Daten verwendet wird. Der Schlüssel ist abrufbar im Attribut keys.
  • keys: Hier befinden sich die öffentlichen Schlüssel des Zustellpunktes.
  • Der signingKid fehlt, da dieser an signierten Nachrichten mit angehängt wird und ebenso im Attribut keys auffindbar ist.
• Ein Schema besteht nun aus einer schemaUri und einem mimeType.
  • Wurde im Zuge der Vereinfachung so umgesetzt. URLs und URNs können in das Feld schemaUri eingetragen werden.

{
  "contactInformation": {
    "legalName": "Max",
    "address": "Mustermann",
    "phone": "+49170123456789",
    "email": "max@mustermann.not",
    "unit": "Musterabteilung XYZ"
  },
  "submissionSchemas": [
    {
      "schemaUri": "urn:xoev-de:xfall:standard:fim-s00000000009_1.0.0",
      "mimeType": "application/xml"
    }
  ],
  "callback": "http://127.0.0.1:4010/voluptas",
  "keys": {
    "my-key-id": {
    }
  },
  "encryptionKid": "my-key-id"
}

Get Destination

• destinationId
• submissionSchemas
• encryptionKid
• keys

Das Attribut contact (vormals technicalContact) wird nicht mehr zurückgegeben, da dies schützenswerte Informationen sind.

Update Destination

• Attribut destinationId ist nicht länger aktualisierbar, da die Id vom Service und nicht vom Nutzer der API verwaltet wird
• Liefert jetzt bei erfolgreicher Aktualisierung die öffentlichen Attribute des Zustellpunktes zurück, anstatt vorher nur { "result": "success" }.

Create Destination

Liefert jetzt bei erfolgreichem Erstellen die öffentlichen Attribute des Zustellpunktes zurück, anstatt vorher nur die destinationId.

Delete Destination

Eigentlich müsste dieser Endpunkt gar keinen Body mitliefern. Damit nicht-konforme Middleware den Request trotzdem sauber routen kann, liefert er jetzt {} anstatt { "result": "success" } zurück.

Application Transfer

• Die Grundstruktur einer Einreichung wurde angepasst, da der Großteil der Informationen nun verschlüsselt übertragen wird.
• Einige Endpunkte und HTTP-Methoden wurden angepasst, um den Ablauf kürzer, einfacher, stabiler und sicherer zu gestalten.
• Metadaten einer Einreichung: Alle Metadaten einer Einreichung werden nun verschlüsselt im Attribut encryptedMetadata übertragen.

Create Application

• Beim Anlegen einer Einreichung muss nun die Id der Destination (Zustellpunktes) mit angegeben werden, da sie nur bei der Anlage der Einreichung notwendig ist und nicht bei den weiteren Aufrufen.
• Struktur um eine Application anzulegen ist nun nur noch { destinationId: …, announcedContentStructure: … }, da sich die Gesamtstruktur geändert hat. In announcedContentStructure wird angegeben ob Fachdaten für diesen Einreichung hochgeladen werden als auch eine Liste an UUIDs die für diesen Einreichung hochgeladen werden. Die Erstellung der UUIDs ist dem Client überlassen.

Add Document to Application

• Der Inhalt des Dokuments wird nun verschlüsselt, daher ist der Content-Type statt application/json nun application/jose
• Als Antwort müsste dieser Endpunkt gar keinen Body mitliefern. Damit nicht-konforme Middleware den Request trotzdem sauber routet: liefert er jetzt {} statt {"result": "success"}

Send Application

• Send Application und Application Data hinzuzufügen ist nun in einem Endpunkt kombiniert, da kein Einreichung ohne Fachdaten übertragen werden können soll.
• Der Aufruf des Endpunktes und die Übertragung der verschlüsselten Fachdaten markiert den Einreichung dann auch als "final" und löst die Übertragung an den Zustellpunkt aus.
• Die Fachdaten sind nun verschlüsselt, wodurch der Content-Type nicht mehr application/json sonder application/jose ist
• Der Response Status ist nicht mehr 200, sondern 202, da die Fachdaten akzeptiert wurden und der Einreichung abgeschickt wird.

Status Endpunkte

• Der upload-status entfällt, da alle Informationen verschlüsselt sind und nun nicht bekannt ist, wie viele Dokumente einer Einreichung bereits hochgeladen wurden.
• Die Informationen zum Status einer Einreichung und dessen Historie sind nun direkt im Einreichung hinterlegt und werden mit zur Verfügung gestellt, wodurch keine separaten Endpunkte mehr notwendig sind.

Application Retrieval

Wie oben schon angesprochen hat sich die Struktur einer Einreichung verändert, sodass ein Einreichung bei der Abholung wie folgt beispielhaft aufgebaut ist:

{
  "destinationId": "879ee109-a690-4db8-ab32-424284184d7d",
  "submissionId": "ce75a6b8-d72f-4b94-b09e-af6be35bc2ae",
  "attachments": [
    "879ee109-a690-4db8-ab32-424284184d7d",
    "2046f9f1-dc89-4440-9c24-c76a8f40d668"
  ],
  "encryptedMetadata": "eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.nlXGAufYH36IABDy0En0LXEhGfC20IZSSchs27ADalHpRoTZKfXhc7hcMk8Y9V8yTP0jYbmrq6NtEg-QS2O5TQFD9Hluhpb631PBgKjPXHYX1Y6iUcR1sXxSUPjePi8F8PcZUZuUJLnhz6myyc9scdAq9BXG2cDJVgkfLI8eZdrqnrY24Hh32_7d5OKLFSpSDrBlqfyQuY8Wbs2h8Wy4Z4hwT1aWDO7b-SqJA181hUbNcF_rR4Mze3Fdtu-3uOIQYgLBBRmN1ZHDLk0EKNCI4B8MyDKLGPoM0ZomV5lVwVWjAMRI4CgQkIQ9rnm-Adof-GbegQL3yJSoNIWRWgzCnZBYZ638QgPllCMVW3WvEVvsgj0Hj16PbofqXTQ5S73LINfP6FZawfC0yMrYjSV_N2L0Lkp2KI3BkJcy-PcFhBnhwu2IsJGAlyDRCnXdVqig8m5yLHuSMQTpLW69LzPEskfsjhnNDR-CEBZpicjMfc-4CL6U7E7YoGc_99DzE5U5._JfqyKH23GiKsnDW.ZtMMjZ3GgcgHss8qbFRhrjl4L0kAfbco-oXICkk.VBHJ00FyDTYjOA_OYfiz5g",
  "encryptedData": "eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.nlXGAufYH36IABDy0En0LXEhGfC20IZSSchs27ADalHpRoTZKfXhc7hcMk8Y9V8yTP0jYbmrq6NtEg-QS2O5TQFD9Hluhpb631PBgKjPXHYX1Y6iUcR1sXxSUPjePi8F8PcZUZuUJLnhz6myyc9scdAq9BXG2cDJVgkfLI8eZdrqnrY24Hh32_7d5OKLFSpSDrBlqfyQuY8Wbs2h8Wy4Z4hwT1aWDO7b-SqJA181hUbNcF_rR4Mze3Fdtu-3uOIQYgLBBRmN1ZHDLk0EKNCI4B8MyDKLGPoM0ZomV5lVwVWjAMRI4CgQkIQ9rnm-Adof-GbegQL3yJSoNIWRWgzCnZBYZ638QgPllCMVW3WvEVvsgj0Hj16PbofqXTQ5S73LINfP6FZawfC0yMrYjSV_N2L0Lkp2KI3BkJcy-PcFhBnhwu2IsJGAlyDRCnXdVqig8m5yLHuSMQTpLW69LzPEskfsjhnNDR-CEBZpicjMfc-4CL6U7E7YoGc_99DzE5U5._JfqyKH23GiKsnDW.ZtMMjZ3GgcgHss8qbFRhrjl4L0kAfbco-oXICkk.VBHJ00FyDTYjOA_OYfiz5g",
  "currentStatus": "queued",
  "statusHistory": [
    {
      "sourceState": "incomplete",
      "targetState": "queued",
      "timestamp": "2021-01-30T08:30:00Z"
    }
  ]
}

Die Fachdaten und Metadaten sind verschlüsselt, die Struktur verändert und daher hat sich auch bei der Abholung einer Einreichung der Prozess verändert bzw. reduziert, indem die Endpunkte für die Abholung der Fachdaten und Metadaten nun kombiniert sind.

Dokument abholen

Bei der Abholung werden nun als Antwort keine Binärdaten mehr zur Verfügung gestellt, sondern die verschlüsselten Inhalte.

Bestätigung der Abholung

• Als Antwort müsste dieser Endpunkt gar keinen Body mitliefern. Damit nicht-konforme Middleware den Request trotzdem sauber routet liefert er jetzt {} (statt vorher {"result": "success"}).

[0.7.0]

Umgesetzte Change Requests

#13 (moved) API Specification: Method of Acknowledge Application endpoint of Subscriber API should be PUT instead of POST

Die Operationen "Send Application" und "Acknowledge Application" wurden auf PUT umgestellt.

Bitte beachten Sie, dass die PUT-Operationen jetzt auf die Status-Resource wirken.

#19 (moved) contentStructure.data.size entfernen

Aufgrund verschiedener Codierungen kann die Größe der Fachdaten (JSON oder XML) in Bytes nicht einfach und verlässlich vorhergesagt werden. Daher wurde die Angabe der Größe der Fachdaten aus den Metadaten entfernt.

#23 (closed) Pattern nicht referenzieren

Im Dokument (document.json) wurde bei der Property signature als Pattern eine Referenz auf base64url.json gesetzt:

    "signature": {
"pattern": {
"$ref": "../common/base64url.json#/pattern"
},
"type": "string",
"description": "Sofern der Antragstellers dieses Dokument signiert hat, wird die Signatur hier base64url-encoded eingebettet"
}

Dies führt beim Swagger-Codegen und dem OpenAPI-Generator zu Fehlern. Um die Codegenerierung zu erleichtern wurde das Pattern dorthin kopiert.

    "signature": {
"type": "string",
"description": "Sofern der Antragstellers dieses Dokument signiert hat, wird die Signatur hier base64url-encoded eingebettet",
"pattern": "^[a-zA-Z0-9-_=]+$"
}

#24 (closed) Keine mehrfachen Typen

Im Modell address-national.json wurde für die Hausnummer (houseNumber) die Typen integer und string definiert. Die Hausnummer sollte eigentlich vom Typ integer sein und Zusätze in den Hausnummerzusatz (houseNumberSuffix) kommen. Um etwas flexibler zu sein, wurde aber alternativ auch ein string für die Hausnummer zugelassen. In FIM wurde die Hausnummer auch als Text-Feld definiert (F00000016).

    "houseNumber": {
"type": [
"string",
"integer"
],
"description": "Hausnummer",
"maxLength": 9,
"pattern": "^[1-9][0-9]{0,3}(-[1-9][0-9]{0,3})?$",
"minimum": 1
}

Die Verwendung von mehr als einem Typen führt bei Codegeneratoren zu Problemen. Daher wird nur noch der Typ string verwendet.

    "houseNumber": {
"type": "string",
"description": "Hausnummer",
"maxLength": 9,
"pattern": "^[1-9][0-9]{0,3}(-[1-9][0-9]{0,3})?$"
}

#25 (moved) Rechtsgrundlage der Verwaltungsleistung

Das Modell "Public Service Type" (public-service-type.json) wurde in "Verwaltungsleistung" umbenannt und hat ein zusätzliches Feld "Rechtsgrundlage" (legalBasis) erhalten.

#33 (closed) Antragsdatum

Unter additionalReferenceInfo wurde eine optionale Property applicationDate (Antragsdatum) hinzugefügt.

#34 (moved) Status History und aktuellen Status verschieben

Die Pfade für den aktuellen Status und die Statushistorie sind jetzt:

• /destinations/{destinationId}/applications/{applicationId}/status - aktueller Status
• /destinations/{destinationId}/applications/{applicationId}/status/history - Statushistorie

#35 (moved) Info/Test Resource hinzufügen

Es wurde in beiden APIs eine Resource /info hinzugefügt, die aktuell die API-Version ausgibt. Dies kann genutzt werden, um die Grundsätzliche Erreichbarkeit der API zu testen und um sicherzustellen, dass eine kompatible Version der API verwendet wird.

#43 (moved) AuthentificationInfo um Liste von verifizierten Feldern ergänzen

Die authentificationInfo wurde um ein Array authenticatedFields ergänzt, das die Felder aus der identityInfo auflistet, für die die Authentifkation gilt. Zusätzlich wurde authentificationMethod zu einem Enum umgewandelt.

#45 Mime-Types

Die Mime-Types in Application Schema wurden gemäß RFC abgebildet werden:

• application/json statt json
• application/xml statt xml

#49 (moved) JSON Web Key Set durch JSON Web Key ersetzt

Die Destination enthält nun einen JWK statt einem JWK Set.

[0.6.0]

Dokumentation

• Fehlercodes dokumentiert
• Erste Schritte überarbeitet