CHANGELOG.md

Changelog

Das Format dieser Datei basiert auf Keep a Changelog.

[Unveröffentlicht] - ????-??-??

Diese Version beinhaltet breaking changes

Allgemein

• Reduktion der Verarbeitung von personenbezogenen Daten
• Daten eines Antrags 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
• Hinzugefügt: Endpunkt /status zur Prüfung ob der Zustelldienst verfügbar ist.

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 schemas 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 optional einem Feld 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"
  },
  "schemas": [
    {
      "schemaURI": "urn:fitko:schema-x"
    }
  ],
  "callback": "http://127.0.0.1:4010/voluptas",
  "keys": {
    "my-key-id": {
      
    }
  },
  "encryptionKid": "my-key-id"
}

Get Destination

• destinationId
• schemas
• 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 eines Antrags 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 eines Antrags: Alle Metadaten eines Antrags werden nun verschlüsselt im Attribut encryptedMetadata übertragen.

Create Application

• Beim Anlegen eines Antrags muss nun die Id der Destination (Zustellpunktes) mit angegeben werden, da sie nur bei der Anlage des Antrags 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 Antrag hochgeladen werden als auch eine Liste an UUIDs die für diesen Antrag 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 Antrag ohne Fachdaten übertragen werden können soll.
• Der Aufruf des Endpunktes und die Übertragung der verschlüsselten Fachdaten markiert den Antrag 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 Antrag abgeschickt wird.

Status Endpunkte

• Der upload-status entfällt, da alle Informationen verschlüssselt sind und nun nicht bekannt ist, wie viele Dokumente eines Antrags bereits hochgeladen wurden.
• Die Informationen zum Status eines Antrags und dessen Historie sind nun direkt im Antrag 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 eines Antrags verändert, sodass ein Antrag bei der Abholung wie folgt beispielhaft aufgebaut ist:

{
  "destinationId": "879ee109-a690-4db8-ab32-424284184d7d",
  "applicationId": "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 eines Antrags 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 (closed) 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 (closed) 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 (closed) 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 (closed) 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 (closed) 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 (closed) 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 (closed) Mime-Types

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

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

#49 (closed) 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

Umgesetzte Change Requests

#3 (closed) Sematic error of the OAS in editor.swagger.io

Das Security Schema darf keine Leerzeichen enthalten und wurde deswegen von "OAuth 2.0" in "OAuth20" umbenannt.

#4 (closed) academicTitle -> doctoralDegrees

Alle Vorkommen von academicTitle wurden durch doctoralDegrees ersetzt.

#5 (closed) telephone -> telephones

Da Arrays mit einem Plural bezeichnet werden sollen wurde telephone durch telephones ersetzt.

#7 (closed) Regex für Hausnummernzusatz ist falsch

Das Pattern für den Hasnummernzusatz ^[\\p{L}0-9. ]*$ war inkorrekt da die Zeichenklassen \p{L} nicht zulässig ist. Es wurde daher zu ^[A-Za-z0-9. ]*$ korrigiert.

#10 (closed) API Specification: senderId and subscriberId in URIs

Die Sender- und Subscriber-ID muss nicht mehr über den Pfad mitgegeben werden sondern wird automatisch über das Token ermittelt. Damit entfallen die IDs als Pfadangabe.

#11 (closed) API Specification: Missing nouns in Sender API URIs endpoints

Die Pfade auf in der Sender API enthielten vor den IDs kein beschreibendes Nomen. Dies wurde korrigiert. Zum Beispiel:

• vorher: /{destinationId}/{applicationId}/data
• nachher: /destinations/{destinationId}/applications/{applicationId}/data

#12 (closed) API Specification: Missing destinationId in Get Status endpoint of Sender

Die Operation "Get Status" wies im Gegensatz zu den anderen Operationen keine vorangestellte Destination-ID auf.

• vorher: /{applicationId}/status
• nachher: /destinations/{destinationId}/applications/{applicationId}/status

#16 (closed) Fachdaten optional

Das Element data in der contentStructure war verpflichtend. Damit mussten Fachdaten übertragen werden. Das Element ist jetzt optional.

[0.5.0]

Übergreifende Änderungen

Basis-URLs

Die Basis-URLs werden ab sofort mit jeder neuen Version geändert, damit ein paralleler Betrieb mehrerer API-Versionen möglich ist. Die Basis-URLs für diese Version sind:

• https://sender.fiep-poc.de/beta5/
• https://subscriber.fiep-poc.de/beta5/

CR-1: Diversen Modellen wurde der Discriminator type hinzugefügt

• models/application/applicant-contact-info.json
• models/application/applicant-contact-info.json
• models/application/applicant-person.json
• models/application/applicant.json
• models/common/address-international.json
• models/common/address-national.json
• models/common/address-postbox.json
• models/common/individual.json
• models/destination-no-id.json

CR-3: Source in Sender ändern

In der Dokumentation werden die Begriffe "Source" und "Sender" synonym verwendet. Um die Dokumentation klarer zu machen, wurden alle Vorkommen von "Source" in "Sender" geändert.

Hinweis: Dies wirkt sich auch auf die OAuth-Scopes aus. Der Scope {senderId}:source:manage wurde in {senderId}:sender:manage geändert.

CR-5: Zusätzliche Properties verbieten

• Wo möglich wurde "additionalProperties": false gesetzt um weitere Properties zu verbieten.
• Bei den Metadaten und der Destination ohne ID musste "additionalProperties": false wieder entfernt werden da sonst keine Ableitung mit allOf möglich ist.

Dokumentation

• Release Notes mit aufgenommen
• Dokumentation zu OAuth integriert
• Token-URL eingetragen
• Postman Collection & Environment integriert

Modelle

Destination

models/destination-no-id.json

eID

• eID-org-acting-person.json aufgelöst und in eID-natural-person.json integriert.

Postfachadresse

models/common/address-national.json models/common/address-postbox.json

• Um ein doppeltes oneOf zu vermeiden wurde die Postfach Adresse aus der nationalen Adresse herausgelöst.

Application Document

models/application/document.json

• Regex Pattern für SHA-256/512 Hash präzisiert: "[0-9A-F]{64,128}" -> "^[A-Fa-f0-9]{64}([A-Fa-f0-9]{64})?$"

Application Sender API

Add Application Data

• Im Erfolgsfall enthält der Body {"result":"success"}

Add Application Document

• Im Erfolgsfall enthält der Body {"result":"success"}

Application Subscriber API

Update Destination

• Im Erfolgsfall enthält der Body {"result":"success"}

Delete Destination

• Im Erfolgsfall enthält der Body {"result":"success"}

Acknowledge Application

• Bugfix: Property final-delivery auf Camelcase umgestellt.
• Bugfix: Angaben von finalDelivery in Acknowledge Application ist verpflichtend.

[0.4.0]

Modelle

• Alle Bezeichner auf CamelCase umgestellt.
• Beispiele angepasst.

Application Metadata

models/application/metadata-no-id.json

• data/mimeType entfernt, da redundant zu data/schema/mimeType

Application Sender API

• Alle Bezeichner auf CamelCase umgestellt.
• Beispiele angepasst.

Application Subscriber API

• Alle Bezeichner auf CamelCase umgestellt.
• Beispiele angepasst.

[0.3.0]

Modelle

Application Metadata

models/application/metadata-no-id.json

• Property data/size ergänzt

eID

models/common/eID-org-acting-person.json

• Property artictic-name in artistic-name umbenannt

Internationale Adresse

models/common/address-international.json

• Property lines:
  • Es müssen mindestens zwei Zeilen angegeben werden
  • Maximallänge 35 Zeichen

Nationale Adresse

models/common/address-national.json

• Alle Eigenschaften mit weiteren Einschränkungen mit Maximallänge oder Pattern versehen

eID

models/common/eID-org-acting-person.json

• Property academic-title in doctoral-degrees umbenannt

Phone

models/common/phone.json

• Property number: Formatbeschränkung gelockert
• Property type entfernt
• Property description hinzugefügt

Phone Number

models/common/phonenr.json

• Unbenutztes Modell gelöscht

[0.2.0] - 2020-03-31

Modelle

Antragsteller - Organisation

models/application/applicant-organization.json

• Property role entfernt
• Property org-validation/validated entfernt
• Property legal-representatives ist jetzt eine $ref auf models/common/individual.json

Antragsteller - Natürliche Person

models/application/applicant-person.json

• Property role entfernt

Application Schema

Das Schema wurde umgebaut und enthält jetzt drei Angaben:

• mime-type: ist entweder json oder xml
• schema-source: Quelle für das Schema. Kann fim oder none sein. Bei none dürfen beliebige Datenstrukturen übertragen werden.
• schema-id: ID des Schemas, ist von der Schemaquelle (schema-source) abhängig.

Person

Die Person (Verzeichnis models/person/) wurde weitestgehend entfernt. Es gibt nur noch das Modell models/common/individual.json für eine natürliche Person.

Phone

models/common/phone.json

• Properties number und type sind jetzt verpflichtend

Destination

Die Destination wurde in mehrere Modelle zerlegt, um dem Sender einen anderen Umfang zu zeigen als dem Subscriber.

Statusübersicht

models/status-overview.json

• Umbenannt: models/status.json → models/status-overview.json
• Enum Wert sending entfernt
• Property since in timestamp umbenannt
• Property number ergänzt

Error Body

models/error-body.json

• Umbenannt: models/error.json → models/error-body.json
• Enthält jetzt ein Array von Fehlern, statt nur einem.

Neue Modelle

• base64: models/common/base64.json
• JSON Web Encryption (JWE): models/common/jwe.json
• JSON Web Key (JWK): models/common/jwk.json

Application Sender API

reference/sender.json

• Vorkommen von "Transfer" in "Application" umbenannt
  • Dadurch sind auch Operation-IDs geändert worden (siehe unten)
• OAuth2 Scopes ergänzt
• Operation "Get Status Entry" (get-application-status-entry) entfernt
• Operation "Get Application Upload Status"
  • Property docs/doc-id ergänzt
• Operation "Create Application": ID in create-application geändert
• Operation "Send Application" (früher "Commit Application"): ID in commit-application geändert

Application Subscriber API

• OAuth2 Scopes ergänzt
• Operation "Acknowledge Application" (früher "Commit Application"): ID in ack-application geändert

Dokumentation

Die Dokumentation im Verzeichnis docs wurde erstellt.