Merge branch 'fix/66-API-Review' into 'master'

Änderungen aus API-Review

See merge request fit-connect/FIT-Connect-PoC!25

CHANGELOG.md

@@ -22,11 +22,8 @@ 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 `contact` gewandert.
-- Das Attribut `technicalContact` wird umbenannt zu `contact`
-- Das Attribut `contact` wurde angepasst, 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.
@@ -43,11 +40,12 @@ Der Aufbau & Umfang von Destination-Objekten hat sich geändert:
 
 ```json
 {
-  "contact": {
-    "firstName": "Max",
-    "lastName": "Mustermann",
+  "contactInformation": {
+    "legalName": "Max",
+    "address": "Mustermann",
+    "phone": "+49170123456789",
     "email": "max@mustermann.not",
-    "organizationName": "Musterorganisation"
+    "unit": "Musterabteilung XYZ"
   },
   "schemas": [
     {
@@ -102,8 +100,8 @@ sauber routen kann, liefert er jetzt `{}` anstatt `{ "result": "success" }` zur
 
 - 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: …, announcedAttachments: … }`, da sich die
-  Gesamtstruktur geändert hat. In `announcedAttachments` wird angegeben ob Fachdaten für diesen Antrag hochgeladen
+- 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.
 

bundle.sh

 #!/usr/bin/env sh
 
-YML_IN="spec/combined.yml"
-YML_OUT="spec/combined-bundled.yml"
+YML_IN="spec/zustelldienst.yml"
+YML_OUT="spec/zustelldienst-bundled.yml"
 
 docker run --rm -v "$(pwd):/work" jeanberu/swagger-cli \
   swagger-cli bundle -t yaml -o "/work/$YML_OUT" "/work/$YML_IN"

spec/endpoints/applications/uuid.yml

@@ -4,7 +4,6 @@ parameters:
 get:
   operationId: get-application
   summary: Antrag abrufen
-  description: Ruft einen Antrag ab
   tags:
     - Application Retrieval
   security:
@@ -57,7 +56,7 @@ post:
   requestBody:
     required: true
     content:
-      application/jose:
+      application/json:
         schema:
           $ref: '../../schemas/submit-application.yml'
   responses:

spec/endpoints/attachments/uuid.yml

@@ -50,7 +50,7 @@ get:
 put:
   operationId: add-application-attachment
   summary: Anhang hinzufügen
-  description: Fügt einem Antrag einen verschlüsselten und base64-kodierten Anhang hinzu.
+  description: Upload des in announcedContentStructure angekündigten Anhangs als JSON Web Encryption unter der mitgeteilten UUID.
   tags:
     - Application Transfer
   security:
@@ -67,7 +67,7 @@ put:
             $ref: '../../examples/encrypted-message.yml'
   responses:
     '201':
-      description: Created
+      description: Anhang erfolgreich hinzugefügt
       content:
         application/json:
           schema:

spec/endpoints/destinations/index.yml

 get:
-  operationId: get-all-destinations
-  summary: Zustellpunkte auflisten
-  description: Auflistung aller verfügbaren Zustellpunkte
+  operationId: get-my-destinations
+  summary: Selbst angelegte Zustellpunkte auflisten
+  description: Mit diesem Request können alle selbst angelegten Zustellpunkte sowie deren Konfigurationen abgerufen werden.
   tags:
     - Destination Management
   security:
@@ -43,7 +43,7 @@ get:
 post:
   operationId: create-destination
   summary: Zustellpunkt anlegen
-  description: Erstellung eines neuen Zustellpunktes mit unterstüzten Antragsschemata.
+  description: Erstellung eines neuen Zustellpunktes mit Konfiguration zum Empfang von Anträgen
   tags:
     - Destination Management
   security:

spec/endpoints/destinations/uuid.yml

@@ -9,7 +9,6 @@ get:
     - Destination Management
   security:
     - OAuth20:
-        - 'destination:manage'
         - 'destination:subscribe'
         - 'destination:send'
   responses:
@@ -47,7 +46,6 @@ get:
 put:
   operationId: update-destination
   summary: Zustellpunkt aktualisieren
-  description: Aktualisiert einen Zustellpunkt.
   tags:
     - Destination Management
   security:
@@ -111,7 +109,7 @@ delete:
         - 'destination:manage'
   responses:
     '200':
-      description: OK
+      description: Zustellpunkt erfolgreich gelöscht.
       content:
         application/json:
           schema:

spec/examples/application.yml

@@ -11,3 +11,8 @@ value:
     - sourceState: incomplete
       targetState: queued
       timestamp: '2021-01-30T08:30:00Z'
+  announcedContentStructure:
+    data: true
+    attachments:
+      - 879ee109-a690-4db8-ab32-424284184d7d
+      - 2046f9f1-dc89-4440-9c24-c76a8f40d668

spec/examples/create-application.yml

 value:
   destinationId: 879ee109-a690-4db8-ab32-424284184d7d
-  announcedAttachments:
+  announcedContentStructure:
     data: true
     attachments:
       - 123ee109-a690-4db8-ab32-424284184d7d

spec/examples/create-destination.yml

 value:
-  contact:
-    firstName: Max
-    lastName: Mustermann
+  contactInformation:
+    legalName: Max
+    address: Musterstr. 31, 10000 Berlin, Deutschland
+    phone: "+49170123456789"
     email: max@mustermann.not
-    organizationName: Musterorganisation
+    unit: Department XYZ
   schemas:
     - schemaURI: urn:fitko:schema-x
   callback: 'http://127.0.0.1:4010/voluptas'
   encryptionKid: my-key-id-0xfff
-  keys:
+  publicKeys:
     keys:
       - kty: RSA
         kid: my-key-id-0xfff

spec/examples/destination-list.yml

@@ -4,17 +4,31 @@ value:
       schemas:
         - schemaURI: urn:fitko:schema-x
       encryptionKid: my-key-id-0xfff
-      keys:
+      publicKeys:
         keys:
           - kty: RSA
             kid: my-key-id-0xfff
+      contactInformation:
+        legalName: Max
+        address: Musterstr. 31, 10000 Berlin, Deutschland
+        phone: "+49170123456789"
+        email: max@mustermann.not
+        unit: Department XYZ
+      callback: 'http://127.0.0.1:4010/voluptas'
     - destinationId: 2f59b8c6-3206-4734-aa21-a7b2a4d92f7a
       schemas:
         - schemaURI: urn:fitko:schema-x
         - schemaURI: urn:fitko:schema-y
           mimeType: application/xml
       encryptionKid: my-key-id-0xeee
-      keys:
+      publicKeys:
         keys:
           - kty: RSA
             kid: my-key-id-0xeee
+      contactInformation:
+        legalName: Max
+        address: Musterstr. 31, 10000 Berlin, Deutschland
+        phone: "+49170123456789"
+        email: max@mustermann.not
+        unit: Department XYZ
+      callback: 'http://127.0.0.1:4010/voluptas'

spec/examples/destination.yml

@@ -3,7 +3,14 @@ value:
   schemas:
     - schemaURI: urn:fitko:schema-x
   encryptionKid: my-key-id-0xfff
-  keys:
+  publicKeys:
     keys:
       - kty: RSA
         kid: my-key-id-0xfff
+  contactInformation:
+    legalName: Max
+    address: Musterstr. 31, 10000 Berlin, Deutschland
+    phone: "+49170123456789"
+    email: max@mustermann.not
+    unit: Department XYZ
+  callback: 'http://127.0.0.1:4010/voluptas'

spec/examples/update-destination.yml

 value:
-  contact:
-    firstName: Max
-    lastName: Mustermann
+  contactInformation:
+    legalName: Max
+    address: Musterstr. 31, 10000 Berlin, Deutschland
+    phone: "+49170123456789"
     email: max@mustermann.not
-    organizationName: Musterorganisation
+    unit: Department XYZ
   schemas:
     - schemaURI: urn:fitko:schema-x
   callback: 'http://127.0.0.1:4010/voluptas'
   encryptionKid: my-key-id-0xfff
-  keys:
+  publicKeys:
     keys:
       - kty: RSA
         kid: my-key-id-0xfff

spec/schemas/application.yml

@@ -41,7 +41,7 @@ properties:
     type: array
     items:
       $ref: './state-transition.yml'
-  announcedAttachments:
+  announcedContentStructure:
     type: object
     required:
       - data

spec/schemas/attachment.yml

 title: Anhang
-description: 'Repräsentation eines Anhangs, der mit einem Antrag verknüpft ist.'
+description: Verschlüsselter Anhang im Format JSON Web Encryption (JWE) laut RFC7516
 type: string
 pattern: '^[a-zA-Z0-9-_=.]+$'

spec/schemas/contact-information.yml

+title: Kontakt
+description: Angaben zum Ansprechpartner des Zustellpunktes
+type: object
+additionalProperties: false
+required:
+  - legalName
+  - address
+  - phone
+  - email
+properties:
+  legalName:
+    type: string
+    description: Juristischer Name der verantwortlichen Organisation
+  address:
+    type: string
+    description: Adresse der verantwortlichen Organisation
+  phone:
+    type: string
+    description: Telefonnummer der verantwortlichen Stelle
+  email:
+    type: string
+    description: Funktionspostfachadresse der verantwortlichen Stelle. Falls nicht vorhanden, kann auch eine personalisierte Adresse des Supportverantwortlichen eingetragen werden.
+  unit:
+    type: string
+    description: Verantwortliche Untereinheit (Abteilung, Referat, etc.) der Organisation. Kann zur Vereinfachung von Klärungsfragen angegeben werden.

spec/schemas/contact.yml

-title: Kontakt
-description: Angaben zum Ansprechpartner des Zustellpunktes
-type: object
-additionalProperties: false
-required:
-  - firstName
-  - lastName
-  - email
-  - organizationName
-properties:
-  firstName:
-    type: string
-    description: Vorname des Ansprechpartners
-  lastName:
-    type: string
-    description: Nachname des Ansprechpartners
-  email:
-    type: string
-    description: E-Mail des Ansprechpartners
-  organizationName:
-    type: string
-    description: Name des Unternehmens des Ansprechpartners

spec/schemas/create-application.yml

@@ -4,14 +4,14 @@ type: object
 additionalProperties: false
 required:
   - destinationId
-  - announcedAttachments
+  - announcedContentStructure
 properties:
   destinationId:
     type: string
     format: uuid
     minLength: 32
     maxLength: 36
-  announcedAttachments:
+  announcedContentStructure:
     type: object
     required:
       - data

spec/schemas/create-destination.yml

@@ -3,14 +3,14 @@ description: 'Notwendige Struktur, um einen Zustellpunkt zu hinterlegen.'
 type: object
 additionalProperties: false
 required:
-  - contact
+  - contactInformation
   - schemas
   - callback
   - encryptionKid
-  - keys
+  - publicKeys
 properties:
-  contact:
-    $ref: './contact.yml'
+  contactInformation:
+    $ref: './contact-information.yml'
   schemas:
     uniqueItems: true
     minItems: 1
@@ -22,11 +22,11 @@ properties:
     type: string
     minLength: 1
     format: uri
-    description: 'Öffentliche URL des Zustellpunktes, an den Anträge geliefert werden sollen.'
+    description: 'Öffentlich erreichbare Callbackadresse, um Benachrichtigungen beim Vorliegen neuer Anträge zu empfangen.'
   encryptionKid:
     type: string
     maxLength: 64
-    description: 'Öffentlicher Teil des Verschlüsselungsschlüssels der Destination. Ist im Attribut `keys` abrufbar.'
+    description: 'Öffentlicher Teil des Verschlüsselungsschlüssels der Destination. Ist im Attribut `publicKeys` abrufbar.'
   # signingKid ist nicht nötig, da diese in einer signierten Nachricht enthalten ist.
-  keys:
+  publicKeys:
     $ref: './jwks.yml'

spec/schemas/destination-list.yml

-title: Liste von Zustellpunkten
+title: Liste selbst angelegter Zustellpunkte
 type: object
 required:
   - destinations
@@ -8,4 +8,4 @@ properties:
     minItems: 0
     items:
       $ref: './destination.yml'
-    description: Eine Auflistung von Zustellpunkten mit ihren öffentlichen Informationen.
+    description: Eine Auflistung aller selbst angelegten Zustellpunkte

spec/schemas/destination.yml

@@ -5,7 +5,9 @@ required:
   - destinationId
   - schemas
   - encryptionKid
-  - keys
+  - publicKeys
+  - contactInformation
+  - callback
 properties:
   destinationId:
     type: string
@@ -23,7 +25,14 @@ properties:
   encryptionKid:
     type: string
     maxLength: 64
-    description: 'Öffentlicher Teil des Verschlüsselungsschlüssels der Destination. Ist im Attribut `keys` abrufbar.'
+    description: 'Öffentlicher Teil des Verschlüsselungsschlüssels der Destination. Ist im Attribut `publicKeys` abrufbar.'
   # signingKid ist nicht nötig, da diese in einer signierten Nachricht enthalten ist.
-  keys:
+  publicKeys:
     $ref: './jwks.yml'
+  contactInformation:
+    $ref: './contact-information.yml'
+  callback:
+    type: string
+    minLength: 1
+    format: uri
+    description: 'Öffentlich erreichbare Callbackadresse, um Benachrichtigungen beim Vorliegen neuer Anträge zu empfangen.'