CHANGELOG.md

# Changelog

Das Format dieser Datei basiert auf [Keep a Changelog](https://keepachangelog.com/de).

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

> 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 `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.

```json
{
  "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 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üssselt 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:

```json
{
  "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 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 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 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 Pattern nicht referenzieren

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

```json
    "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.

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

#### #24 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).

```json
    "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.

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

#### #25 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 Antragsdatum

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

#### #34 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 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 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 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](../5_Status-_und_Fehlercodes.md) dokumentiert
- [Erste Schritte](../1_Getting_Started.md) überarbeitet

### Umgesetzte Change Requests

#### #3 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 academicTitle -> doctoralDegrees

Alle Vorkommen von `academicTitle` wurden durch `doctoralDegrees` ersetzt.

#### #5 telephone -> telephones

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

#### #7 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 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 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 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 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.

<!-- theme: warning -->
> **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.