Merge branch 'document-application-metadata-scheme' into 'master'

Erste Dokumentation des Antragsmetadatenschemas

See merge request fit-connect/api!27

.gitlab-ci.yml

@@ -16,9 +16,18 @@ build:
   stage: build
   image: $CI_REGISTRY/node:current-alpine
   before_script:
+    - echo 'http://dl-cdn.alpinelinux.org/alpine/edge/community' >> /etc/apk/repositories
+    - apk update
+    - apk add yq bash
+    - yq -V
     - npm install -g @apidevtools/swagger-cli
     - mkdir dist
-  script: swagger-cli bundle -t yaml -o dist/zustelldienst.yml spec/zustelldienst.yml
+  script:
+    - ./bundle-docs.sh
+    - yq e '.info.description.$ref = "../dist/docs.bundled.md"' -i spec/zustelldienst.yml
+    - cp metadata-schema/antragsmetadaten.schema.json dist/
+    - swagger-cli bundle -t yaml -o dist/zustelldienst.yml spec/zustelldienst.yml
+    - yq e '.components.schemas.Antragsmetadaten.$ref = "./antragsmetadaten.schema.json"' -i dist/zustelldienst.yml
   # find ./spec -type f -name "*.yml" -exec sh -c 'swagger-cli bundle -t yaml -o dist/$(basename {}) {}' \;
   artifacts:
     expose_as: 'Built API spec'
@@ -42,8 +51,11 @@ upload:
     - chmod 700 ~/.ssh
     - echo "$UBERSPACE_KNOWN_HOST" >> ~/.ssh/known_hosts
   script:
-    - sed "s,REPLACEME,$CI_COMMIT_TAG/zustelldienst.yml,g" ui/config.js.template > ui/config.js
+    - sed "s,API_VERSION,$CI_COMMIT_TAG/zustelldienst.yml,g" ui/config.js.template > ui/config.js
+    - sed "-i "s,API_VERSION,$CI_COMMIT_TAG" dist/zustelldienst.yml
+    - sed "-i "s,API_VERSION,$CI_COMMIT_TAG" dist/antragsmetadaten.schema.json
     - rsync -rLvz --size-only --checksum -e "ssh -o CheckHostIP=no" --ipv4 --progress ./ui/. fitko@dorado.uberspace.de:html/
+    - rsync -rLvz --size-only --checksum -e "ssh -o CheckHostIP=no" --ipv4 --progress ./assets/. fitko@dorado.uberspace.de:html/$CI_COMMIT_TAG/
     - rsync -rLvz --size-only --checksum -e "ssh -o CheckHostIP=no" --ipv4 --progress ./dist/. fitko@dorado.uberspace.de:html/$CI_COMMIT_TAG/
 
 #release-new-api-version:

.spectral.yml

@@ -11,3 +11,7 @@ rules:
   response-with-json-object: error
   paths-status-return-problem: off
   paths-status-problem-schema: off
+
+except:
+  '#/info/version':
+    - use-semver
\ No newline at end of file

bundle-docs.sh

+#!/usr/bin/env bash
+
+mkdir -p dist
+
+# Concatenate all files (enforce newline between files)
+cut -b 1- docs/_* docs/{1..5}_* docs/Detailinformationen/*.md > dist/docs.bundled.md
+# Add additional newlines before each heading (to avoid issues when, e.g., a table is followed by a heading)
+sed -i 's/^#/\n\n#/g' dist/docs.bundled.md

docs/1_Getting_Started.md

 # Erste Schritte zur API Nutzung
 
-<!-- theme: info -->
+## ① Account registrieren
 
-> ## ① Account registrieren
 > Registrieren Sie sich für ein Zugriff, um mit Ihren Client auf die API zuzugreifen. Im Rahmen der Registrierung bekommen Sie für die gewünschte API die Client-ID und Zugriffdaten mitgeteilt. Da zum aktuellen Zeitpunkt keine Sandbox Umgebung bereitstellt, wird empfohlen, sich für beide Seiten zu registieren, um für komplexere Tests mit einem REST Client die API der Gegenseite anzusprechen (Siehe Postman Nutzung in Schritt 2). ➡ [Registrierung zur API Nutzung](./4_Authentifizierung_und_Autorisierung.md)
 
-> ## ② API ausprobieren
-> In der Navigation auf linken Seite finden Sie die jeweiligen API Referenzen für die Nutzung der APIs unter den Reitern `Application Sender API` und `Application Subscriber API` 
-Für einen einfachen Einstieg zum Test der API können Sie die bereitgestellte Postman Collection nutzen und mit dem Postman REST Client die Anfragen an die API durchführen. Hiermit können Sie auch die Gegenseite (Sender oder Empfänger von Anträgen simulieren) (➡ [Testen mit Postman](./Detailinformationen/Postman.md). Nähere Informationen zu Postman siehe https://www.postman.com/) 
+## ② API ausprobieren
+
+> In der Navigation auf linken Seite finden Sie die jeweiligen API Referenzen für die Nutzung der APIs unter den Reitern `Application Sender API` und `Application Subscriber API`
+Für einen einfachen Einstieg zum Test der API können Sie die bereitgestellte Postman Collection nutzen und mit dem Postman REST Client die Anfragen an die API durchführen. Hiermit können Sie auch die Gegenseite (Sender oder Empfänger von Anträgen simulieren) (➡ [Testen mit Postman](./Detailinformationen/Postman.md). Nähere Informationen zu Postman siehe <https://www.postman.com/>)
 Alternativ können Sie die Anfragen auch mittels eigener Anwendungen oder alternativer REST Clients durchführen.
 
-> ## ③ OAuth Token vor der API Nutzung abrufen
+## ③ OAuth Token vor der API Nutzung abrufen
+
 > Für jede Anfrage an die API Endpunkte ist ein gültiger JWT-Token mit der Anfrage mitzusenden. Für nähere Informationen zum Abruf eines JWT-Token siehe ➡ [OAuth Details](./Detailinformationen/OAuth.md)
 
-> ## ④ Spezifikation lokal nutzen
-> Sofern Sie einen lokalen Zugriff auf die Quellen der Spezifikation im OpenAPI Format (bspw. für Code Generatoren) benötigen, finden Sie diese hier: ➡[FIT-Connect-PoC-v0.6.zip](https://github.com/fiep-poc/assets/raw/master/spec/FIT-Connect-PoC-v0.6.zip)
+## ④ Spezifikation lokal nutzen
 
+> Sofern Sie einen lokalen Zugriff auf die Quellen der Spezifikation im OpenAPI Format (bspw. für Code Generatoren) benötigen, finden Sie diese hier: ➡[FIT-Connect-API-Spec.yml](https://fitko.uber.space/API_VERSION/zustelldienst.yml)
 
 ## Beispiel mit `curl`
 
@@ -44,6 +45,7 @@ curl --silent --header "Authorization: Bearer ${TOKEN}" https://sender-test.fiep
 <!-- theme: success -->
 
 > ### Service Desk
+
 > Für Fragen, Anregungen und sonstiges Feedback steht Ihnen unser
 > [FIT-Connect Service Desk](https://jira.fiep-poc.de/servicedesk/customer/portal/1)
 > zur Verfügung.

docs/Detailinformationen/Callback.md

-# Callback Benachrichtigungen
-
-Callbacks sind einfache Webhooks und dienen dazu, API Nutzer über relevante Ereignisse aktiv zu informieren, anstatt das der Client über konstante Abfragen an der API potentielle Änderungen oder Eigenisse abzufragen muss. 
-
-Aktuell wird den Subscribern eine Callback Funktion angeboten, um diese über abrufbereite Anträge in ihren Destinations zu informieren.
-
-## Callback registrieren
-Beim [anlegen](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations/post) oder [aktualisieren](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations~1{destination-id}/put) einer Destination sollte ein Callback angegeben werden.
-
-```json
-{
-  "organization": {
-    "organization-name": "Gewerbeamt Musterhausen"
-  },
-  "technical-contact": [
-    {
-      "first-name": "Werner",
-      "last-name": "Mustermann",
-      "contact": {
-        "telephones": [
-          {
-            "number": "+49 89 32168-42",
-            "mobile": false,
-            "type": "work"
-          }
-        ]
-      }
-    }
-  ],
-  "callback": {
-    "callback-url": "https://www.example.com/callback"
-  }
-}
-```
-
-## Callback ausführen
-Trifft nun ein neuer Antrag ein, so sendet der Zustelldienst einen HTTP-POST-Request an die angegebene Adresse. Im Body des Requests werden die `destination-id` und die `application-id`s der wartenden Anträge (i.d.R. genau eine) aufgelistet.
-
-```json
-{
-  "destination-id": "821",
-  "applications": [
-    {
-      "application-id": "98472"
-    }
-  ]
-}
-```
-
-## Callback nur bei Inaktivität
-Nach einem Callback wartet der Zustelldienst eine gewisse Zeit (z.B. 5 Minuten) bis zum nächsten Callback, auch wenn in dieser Zeit neue Anträge eintreffen. Diese Wartezeit wird bei Aktivität der Destination (z.B. Abfrage der Queue oder Abholen von Anträgen) verlängert.

docs/Detailinformationen/Metadaten.md

+# Antragsmetadaten
+
+Die Antragsmetadaten beschreiben die Struktur des Antrags und dessen Inhalte, wie beispielsweise Anhänge oder die Fachdaten. Zustätzlich können weitere Informationen über den/die AntragsstellerInnen hinterlegt werden. Eine genaue Definition ist unter XYZ zu finden bzw. direkt im [Schema](/API_VERSION/antragsmetadaten.schema.json) zu finden.
+
+Im Folgenden wird nun beschrieben, wie für das Versenden eines Antrags das Schema aufgebaut und befüllt wird, sowie beim Empfangen eines Antrags dieser entschlüsselt und gegen das Schema validiert wird.
+
+## Prozess: Versenden eines Antrages
+
+### Anlegen eines neuen Antrags
+
+Das Anlegen eines neuen Antrags kann über die API getätigt werden. Dafür muss ein HTTP POST Nachricht versendet werden, die definiert, an welchen Zustellpunkt der Antrag versendet werden soll und welche Inhalte übermittelt werden sollen. Die Inhalte umfassen hierbei die Identifikatoren der Anhänge als UUIDs und die Information, ob Fachdaten mit versendet werden oder nicht.
+
+```text
+curl --data '{ "destinationId": "<UUID>", "announcedContentStructure": {} }' -H 'Content-Type: application/json' -H 'X-AnwenderId: <Id>' -X POST <URL>/applications/
+```
+
+```text
+curl --data '{ "destinationId": "7a2668ad-3081-407c-9358-7ce4b6144b02", "announcedContentStructure": {"data": "false", "attachments": []} }' -H 'Content-Type: application/json' -H 'X-AnwenderId: sender' -X POST localhost:8080/applications/
+> {
+  "destinationId": "7a2668ad-3081-407c-9358-7ce4b6144b02",
+  "applicationId": "9d618546-0ff7-4e93-9f15-714e5dd1bf12"
+}
+```
+
+### Definition der Antragsmetadaten
+
+Das Minimum, was an Antragsmetadaten hinterlegt werden muss, ist eine Beschreibung der Struktur des Antrags, sowie die ID des Antrags selbst.
+In der Beschreibung der Struktur muss angegeben werden, ob Fachdaten mit versendet werden und in welchem Format diese sind. Des Weiteren können Anhänge mit ihren Metainformationen beschrieben werden, die dem Antrag beigefügt sind.
+
+Ein Beispiel hierfür ist unten dargestellt:
+
+```json
+{
+  "contentStructure": {
+    "data": {
+      "schema": {
+        "mimeType": "application/json",
+        "schemaSource": "https://schema.fitko.de/fim/fim.S00000147.00000147001002.json"
+      }
+    },
+    "docs": [
+      {
+        "docId": "1",
+        "purpose": "form",
+        "size": 13046,
+        "mimeType": "application/pdf",
+        "filename": "test.pdf",
+        "description": "Das Antragsformular",
+        "lang": {
+          "lang": "de",
+          "region": "DE"
+        },
+        "hash": {
+          "algorithm": "SHA-256",
+          "digest": "bf37d894fdf9aeade63975ed648d49c3e8a7a773923597d2418915f54cd7c3b9"
+        }
+      }
+    ]
+  },
+  "applicationId": "ce75a6b8-d72f-4b94-b09e-af6be35bc2ae"
+}
+```
+
+Abhängig von den Rahmenbedingungen können die weiteren Felder, die im Antragsmetadatenschema definiert sind, befüllt werden und mitversendet werden. Ob diese jedoch ausgewertet werden oder nicht hängt von dem entsprechenden Empfänger ab.
+
+### Verschlüsseln
+
+Nun wird das JSON-Objekt aus dem vorherigen Schritt verschlüsselt und kann dann im nächsten Schritt mit dem Antrag abgesendet werden.
+Die Verschlüsselung eines Objektes mit Hilfe von JWE ist im Bereich "[Verschlüsselte Übertragung](#overview--verschlüsselte-übertragung)" genauer beschrieben und kann dort nachgelesen werden.
+
+### Versenden des Antrags
+
+Sobald alle Anhänge eines Antrags hochgeladen sind, kann der Antrag abgesendet werden. Hierfür müssen die verschlüsselten Metadaten und, falls angekündigt, die Fachdaten über eine HTTP POST Nachricht gesendet werden. Ein Beispiel hierfür ist im folgenden Ausschnitt aufgezeigt:
+
+```text
+curl --data '{ "encryptedMetadata": "<jose-String>" }' -H 'Content-Type: application/json' -H 'X-AnwenderId: <Id>' -X POST <URL>/applications/<UUID>
+```
+
+```text
+curl --data '{ "encryptedMetadata": "eyJhbGciOiAiUlNBLU9BRVAiLCAiZW5jIjogIkExMjhDQkMtSFMyNTYifQ.SsLgP2bNKYDYGzHvLYY7rsVEBHSms6_jW-WfglHqD9giJhWwrOwqLZOaoOycsf_EBJCkHq9-vbxRb7WiNdy_C9J0_RnRRBGII6z_G4bVb18bkbJMeZMV6vpUut_iuRWoct_weg_VZ3iR2xMbl-yE8Hnc63pAGJcIwngfZ3sMX8rBeni_koxCc88LhioP8zRQxNkoNpvw-kTCz0xv6SU_zL8p79_-_2zilVyMt76Pc7WV46iI3EWIvP6SG04sguaTzrDXCLp6ykLGaXB7NRFJ5PJ9Lmh5yinAJzCdWQ-4XKKkNPorSiVmRiRSQ4z0S2eo2LtvqJhXCrghKpBNgbtnJQ.Awelp3ryBVpdFhRckQ-KKw.1MyZ-3nky1EFO4UgTB-9C2EHpYh1Z-ij0RbiuuMez70nIH7uqL9hlhskutO0oPjqdpmNc9glSmO9pheMH2DVag.Xccck85XZMvG-fAJ6oDnAw" }' -H 'Content-Type: application/json' -H 'X-AnwenderId: sender' -X POST localhost:8080/applications/9d618546-0ff7-4e93-9f15-714e5dd1bf12
+> {
+  "destinationId": "7a2668ad-3081-407c-9358-7ce4b6144b02",
+  "applicationId": "9d618546-0ff7-4e93-9f15-714e5dd1bf12",
+  "attachments": [],
+  "currentStatus": "forwarded",
+  "encryptedMetadata": "eyJhbGciOiAiUlNBLU9BRVAiLCAiZW5jIjogIkExMjhDQkMtSFMyNTYifQ.SsLgP2bNKYDYGzHvLYY7rsVEBHSms6_jW-WfglHqD9giJhWwrOwqLZOaoOycsf_EBJCkHq9-vbxRb7WiNdy_C9J0_RnRRBGII6z_G4bVb18bkbJMeZMV6vpUut_iuRWoct_weg_VZ3iR2xMbl-yE8Hnc63pAGJcIwngfZ3sMX8rBeni_koxCc88LhioP8zRQxNkoNpvw-kTCz0xv6SU_zL8p79_-_2zilVyMt76Pc7WV46iI3EWIvP6SG04sguaTzrDXCLp6ykLGaXB7NRFJ5PJ9Lmh5yinAJzCdWQ-4XKKkNPorSiVmRiRSQ4z0S2eo2LtvqJhXCrghKpBNgbtnJQ.Awelp3ryBVpdFhRckQ-KKw.1MyZ-3nky1EFO4UgTB-9C2EHpYh1Z-ij0RbiuuMez70nIH7uqL9hlhskutO0oPjqdpmNc9glSmO9pheMH2DVag.Xccck85XZMvG-fAJ6oDnAw",
+  "encryptedData": null,
+  "statusHistory": [
+    {
+      "sourceState": "queued",
+      "targetState": "forwarded",
+      "details": "Callback von Destination 7a2668ad-3081-407c-9358-7ce4b6144b02 ausgelöst.",
+      "timestamp": "2021-05-26T09:12:59.68968+02:00"
+    },
+    {
+      "sourceState": "incomplete",
+      "targetState": "queued",
+      "details": "Antrag versendet durch sender",
+      "timestamp": "2021-05-26T09:12:58.728397+02:00"
+    }
+  ],
+  "announcedContentStructure": {
+    "data": false,
+    "attachments": []
+  }
+}
+```
+
+## Prozess: Empfangen und verarbeiten eines Antrags
+
+### Abfragen des Antrags
+
+Wenn ein neuer Antrag bereitsteht, kann dieser über mehrere Befehle heruntergeladen werden. Mehrere dahingehend, da erst alle allgemeinen Informationen zum Antrag heruntergeladen werden müssen und dann, falls notwendig alle mit ihm verbundenen Anhänge.
+
+```text
+curl -H 'X-AnwenderId: <Id>' -X GET <URL>/applications/<UUID>
+
+# Falls ein Antrag noch entsprechend Anhänge besitzt, können diese über folgenden Befehl heruntergeladen werden:
+curl -H 'X-AnwenderId: <Id>' -X GET <URL>/applications/<UUID>/attachments/<UUID>
+```
+
+```text
+curl -H 'X-AnwenderId: subscriber' -X GET localhost:8080/applications/9d618546-0ff7-4e93-9f15-714e5dd1bf12
+> {
+  "destinationId": "7a2668ad-3081-407c-9358-7ce4b6144b02",
+  "applicationId": "9d618546-0ff7-4e93-9f15-714e5dd1bf12",
+  "attachments": [],
+  "currentStatus": "forwarded",
+  "encryptedMetadata": "eyJhbGciOiAiUlNBLU9BRVAiLCAiZW5jIjogIkExMjhDQkMtSFMyNTYifQ.SsLgP2bNKYDYGzHvLYY7rsVEBHSms6_jW-WfglHqD9giJhWwrOwqLZOaoOycsf_EBJCkHq9-vbxRb7WiNdy_C9J0_RnRRBGII6z_G4bVb18bkbJMeZMV6vpUut_iuRWoct_weg_VZ3iR2xMbl-yE8Hnc63pAGJcIwngfZ3sMX8rBeni_koxCc88LhioP8zRQxNkoNpvw-kTCz0xv6SU_zL8p79_-_2zilVyMt76Pc7WV46iI3EWIvP6SG04sguaTzrDXCLp6ykLGaXB7NRFJ5PJ9Lmh5yinAJzCdWQ-4XKKkNPorSiVmRiRSQ4z0S2eo2LtvqJhXCrghKpBNgbtnJQ.Awelp3ryBVpdFhRckQ-KKw.1MyZ-3nky1EFO4UgTB-9C2EHpYh1Z-ij0RbiuuMez70nIH7uqL9hlhskutO0oPjqdpmNc9glSmO9pheMH2DVag.Xccck85XZMvG-fAJ6oDnAw",
+  "encryptedData": null,
+  "statusHistory": [
+    {
+      "sourceState": "queued",
+      "targetState": "forwarded",
+      "details": "Callback von Destination 7a2668ad-3081-407c-9358-7ce4b6144b02 ausgelöst.",
+      "timestamp": "2021-05-26T09:12:59.68968+02:00"
+    },
+    {
+      "sourceState": "incomplete",
+      "targetState": "queued",
+      "details": "Antrag versendet durch sender",
+      "timestamp": "2021-05-26T09:12:58.728397+02:00"
+    }
+  ],
+  "announcedContentStructure": {
+    "data": false,
+    "attachments": []
+  }
+}
+```
+
+### Entschlüsseln
+
+Um den Antrag korrekt verarbeiten und überprüfen zu können müssen zuerst alle verschlüsselten Informationen entschlüsselt werden. Darunter fallen beispielsweise die Antragsmetadaten, die Fachdaten (falls vorhanden) oder Dokumente (falls vorhanden).
+
+Die Entschlüsselung eines solchen Objektes mit Hilfe von JWE ist im Bereich "[Verschlüsselte Übertragung](#overview--verschlüsselte-übertragung)" genauer beschrieben und kann dort nachgelesen werden.
+
+### Validierung der Antragsmetadaten
+
+Das Minimum, was an Information vorhanden sein muss sind die Felder `contentStructure` und `applicationId`. Zustäzlich können je nach Anwendungsfall oder Notwendigkeit weitere Felder auf Existenz überprüft werden. Die gültigen Formate sind im Schema definiert und können mit Hilfe von Bibliotheken für die Validierung einer Instanz von Antragsmetadaten verwendet werden. Beispiele für die Definition von Formaten für Felder sind unten aufgeführt.
+
+```json
+{
+  ...
+  "country": {
+    "type": "string",
+    "description": "Staat gemäß Codeliste [https://www.xrepository.de/details/urn:de:bund:destatis:bevoelkerungsstatistik:schluessel:staat](Codeliste Staat aus der Staats- und Gebietssystematik des Statistischen Bundesamtes)",
+    "minLength": 3,
+    "maxLength": 3,
+    "pattern": "^[0-9]{3}$"
+  },
+  ...
+  "postalCode": {
+    "type": "string",
+    "description": "Postleitzahl",
+    "minLength": 5,
+    "maxLength": 5,
+    "pattern": "^([0]{1}[1-9]{1}|[1-9]{1}[0-9]{1})[0-9]{3}$"
+  },
+  ...
+  "applicationId": {
+    "type": "string",
+    "format": "uuid",
+    "pattern": "^[-_.A-Za-z0-9]+$",
+    "description": "ID des Antrags"
+  },
+  ...
+}
+```
+
+### Verarbeiten des Antrags
+
+Nachdem nun der Antrag vollständig heruntergeladen wurde und validiert wurde, sollte dieser entsprechend bestätigt werden. Dies muss über ein HTTP PUT, wie unten aufgezeigt, durchgeführt werden.
+
+```text
+curl -H 'X-AnwenderId: <Id>' -X PUT <URL>/applications/<UUID>
+```
+
+```text
+curl -H 'X-AnwenderId: subscriber' -X PUT localhost:8080/applications/9d618546-0ff7-4e93-9f15-714e5dd1bf12
+> {}
+```

docs/_Overview.md

@@ -4,37 +4,41 @@ Willkommen auf der API Dokumentation für die XFall REST API von FIT-Connect. Di
 
 ## Was ist die XFall API und was unterscheidet diese API vom bisherigen XFall Standard?
 
-Die XFall API baut auf den bisherigen Konzepten und Erfahrungen des bestehenden IT-Planungsrats Standards XFall auf. 
+Die XFall API baut auf den bisherigen Konzepten und Erfahrungen des bestehenden IT-Planungsrats Standards XFall auf.
 
-> Die übergreifende Zielstellung des Standards XFall besteht darin, Anträge und Berichte, die aus vorgelagerten Systemen (bspw. Onlineantragsdienste, Fachportale oder Berichtssysteme) erstellt werden, in die unterschiedlichen Systeme der elektronischen Verfahrensbearbeitung (bspw. Fachverfahren, Dokumentenmanagementsystem oder Prozessplattformen) zu übergeben. 
+> Die übergreifende Zielstellung des Standards XFall besteht darin, Anträge und Berichte, die aus vorgelagerten Systemen (bspw. Onlineantragsdienste, Fachportale oder Berichtssysteme) erstellt werden, in die unterschiedlichen Systeme der elektronischen Verfahrensbearbeitung (bspw. Fachverfahren, Dokumentenmanagementsystem oder Prozessplattformen) zu übergeben.
 
 Bei der Entwicklung der XFall API wurden viele Konzepte mit Hinblick auf die neuen Erfordernisse des Onlinezugangsgesetzes, der SDG-Verordnung sowie den Anforderungen digitaler Geschäftsmodelle weiterentwickelt. Technisch nutzt die XFall API auf einen leichtgewichtigen RESTful-Architekturstil und baut auf der föderalen Antragsübertragungsarchitektur von FIT-Connect auf.
 
 ## Was macht die XFall API und wie kann diese genutzt werden?
 
 Die XFall API besteht aus zwei getrennt nutzbaren APIs:
-- Für antragsempfangende Systeme wird eine `Application Subscriber API` für den Empfang von Anträgen sowie eine `Callback` / Webhook Funktion für die technische Benachrichtigung über vorliegende Anträge angeboten. 
+
+- Für antragsempfangende Systeme wird eine `Application Subscriber API` für den Empfang von Anträgen sowie eine `Callback` / Webhook Funktion für die technische Benachrichtigung über vorliegende Anträge angeboten.
 - Für antragssendende Systeme wird eine `Application Sender API` angeboten, um an beliebige antragsempfangende Systeme Anträge zu senden, die sich mit einem Zustellpunkt registriert haben.
 
 Diese beiden APIs werden durch einen zentralen Intermediär (`XFall Zustelldienst`) bereitgestellt. Um auf diese APIs zuzugreifen, müssen interessierte Entwickler ihre Anwendungen beim FIT-Connect Autorisierungsdienst vorab registrieren.
 
 ### Zusammenspiel der APIs in der Antragsübermittlung
+
 ![Applicationtransfer_Architecture](../assets/images/api_overview/XFall_Integration_Architecture.png "Antragsübertragungsarchitektur FIT-Connect")
 
 Über die `Application Subscriber API` können die zuständigen Stellen für ihre Systeme einen Zustellpunkt eröffnen, der über eine `destination-Id` eindeutig adressierbar ist. Für diese Zustellpunkte legen die zuständigen Stellen alle fachlichen Vorgaben (Zulässige Fachstandards, Verschlüsselung, Datenformate etc.) fest, damit eine medienbruchfreie Weiterverarbeitung in ihren Systemen gewährleistet ist. Über die Angabe der `destination-Id` in der `Application Sender API` können beliebige antragssendende Systemen Anträge an die zuständige Stelle senden.
 
-Dieser Zustellpunkt ist jedoch vorab für eine Verwaltungsleistung und den jeweiligen örtlichen Antragskontext (bspw. Ort der Antragsstellung) korrekt zu ermitteln. Damit die Ermittlung des korrekten Zustellpunkts skalierbar für das ganze Bundesgebiet funktioniert, ist langfristig vorgesehen, die `destination-Id` in den Leistungs- und Zuständigkeitsinformationen des jeweils bekannten Zuständigkeitsfinders zu hinterlegen. Diese dezentral gepflegten Informationen sollen durch das Online-Gateway (https://www.onlinezugangsgesetz.de/Webs/OZG/DE/umsetzung/portalverbund/online-gateway/online-gateway-node.html) gebündelt und über eine offene API im XZuFi Format (https://www.xrepository.de/details/urn:xoev-de:fim:standard:xzufi) nutzbar gemacht werden.
+Dieser Zustellpunkt ist jedoch vorab für eine Verwaltungsleistung und den jeweiligen örtlichen Antragskontext (bspw. Ort der Antragsstellung) korrekt zu ermitteln. Damit die Ermittlung des korrekten Zustellpunkts skalierbar für das ganze Bundesgebiet funktioniert, ist langfristig vorgesehen, die `destination-Id` in den Leistungs- und Zuständigkeitsinformationen des jeweils bekannten Zuständigkeitsfinders zu hinterlegen. Diese dezentral gepflegten Informationen sollen durch das Online-Gateway (<https://www.onlinezugangsgesetz.de/Webs/OZG/DE/umsetzung/portalverbund/online-gateway/online-gateway-node.html>) gebündelt und über eine offene API im XZuFi Format (<https://www.xrepository.de/details/urn:xoev-de:fim:standard:xzufi>) nutzbar gemacht werden.
 
 ![Applicationtransfer_Architecture](https://raw.githubusercontent.com/fiep-poc/assets/master/images/api_overview/Pflege%20und%20Ermittlung%20destination-Id.jpg "Pflege und Ermittlung der destination-Id")
 
 ## Für wen ist die XFall API gedacht und warum sollte ich sie nutzen?
 
 Die XFall API ist für alle Hersteller, Entwickler und Verfahrensverantwortliche von antragssendenden und antragsempfangenden Systemen gedacht. Insbesondere folgende Systeme mit bundesweiten Nutzungsszenarien sollen mit der XFall API unterstützt werden:
+
 - **Einer für alle (EfA) Verfahren**: Länderübergreifend entwickelte Antragsverfahren für eine bestimmte Verwaltungsleistung oder ein Leistungsbündel, die entweder in verschiedenen Ländern nachnutzbar betrieben werden oder länderübergreifend als gemeinsamer Antragsdienst für alle zuständigen Stellen betrieben werden.
 - **Antragsgeneratoren / Antragsmanagementsysteme**: Standardsoftware zur Erstellung und dem Betrieb von direkt nutzbaren Onlineantragsdiensten, die im ganzen Bundesgebiet bei einzelnen Stellen oder Gebietskörperschaften (bspw. als Basiskomponente) im Einsatz sind.
 - **Als Standardsoftware bereitgestellte Fachverfahrenssoftware, Prozessplattformen oder Dokumentenmanagementsysteme**: Bundesweit angebotene und eingesetzte Standardsoftware, die von den zuständigen Stellen für die Antragsbearbeitung eingesetzt wird.
 
-Für diese Systeme bietet die XFall bei der schnellen und wirtschaftlichen Realisierung medienbruchfreier Antragsprozesse eine Reihe von Mehrwerten: 
+Für diese Systeme bietet die XFall bei der schnellen und wirtschaftlichen Realisierung medienbruchfreier Antragsprozesse eine Reihe von Mehrwerten:
+
 - **Plug and Play Anbindung an die föderale Antragsübermittlung**: Durch die zentral bereitgestellten APIs und die Nutzung der bestehenden Zuständigkeitsfinderinfrastruktur können Systeme schnell an eine föderale Antragsübermittlungsinfrastruktur angebunden werden, ohne eigene Infrastrukturen hierfür zu beauftragen oder aufzubauen.
 - **Leichgewichtige APIs und Industriestandards**: Die XFall API baut auf leichgewichtigen RESTful API Ansätzen auf und nutzt verbreitete Industriestandards wie die OpenAPI Specification und OAuth 2.0, sodass kein spezialisiertes Know-How und spezifische Softwarekomponenten für die Anbindung erforderlich sind.
 - **Flexibilität in der Antragsübermittlung**: Die XFall API verbindet Flexibilität und Standardisierung. Während die XFall API eine einheitliche Metadatenstruktur festlegt, um Anträge strukturiert zu verarbeiten, können beliebige Fachstandards und Anhänge übertragen werden. Auch die Übertragung von Anträgen im PDF Format ist möglich, solange für die Antragsdaten noch kein FIM Schema vorhanden ist.

spec/zustelldienst.yml

 openapi: 3.0.0
 info:
-  version: '1.0.0-alpha'
+  version: 'API_VERSION'
   title: Antragsmanagement API für Antragsverfahren und Berichtspflichten
-  description: Übergreifende API Schnittstelle des Zustelldienstes.
   contact:
     name: FITKO
     url: 'https://www.fitko.de/'

ui/config.js.template

 // Localhost: python -m http.server
-// sed 's,REPLACEME,https://example.com/spec.yml,g' ui/config.js.template > ui/config.js
+// sed 's,API_VERSION,https://example.com/spec.yml,g' ui/config.js.template > ui/config.js
 
-export const SPEC_URL = "REPLACEME";
+export const SPEC_URL = "API_VERSION";

ui/index.html

@@ -16,14 +16,17 @@
 <!--<rapi-doc spec-url = "poc/reference/0_xfall_deref_snippets.json" -->
 <rapi-doc id="thedoc"
           render-style="focused"
-          show-info="true"
-          show-header="true"
-          show-components="true"
+
           theme="light"
           xprimary-color="#11171a"
           header-color="#263238"
           nav-bg-color="#263238"
 
+          show-info="true"
+          show-header="true"
+          show-components="true"
+          allow-spec-file-load="false"
+
           info-description-headings-in-navbar="true">
     <!-- content at the top -->