From 8181c0f435f4312d6c42735a1d91f2376e0c9f07 Mon Sep 17 00:00:00 2001
From: Andreas Huber <anh@fjd.de>
Date: Mon, 30 Mar 2020 08:29:32 +0200
Subject: [PATCH] Korrekturen an der Dokumentation
---
...uick Reference.md => 2_Quick_Reference.md} | 51 +++++++------------
docs/3_Use_Cases_der_API.md | 6 +--
docs/5_Status-_und_Fehlercodes.md | 3 +-
docs/6_Callback.md | 51 +++++++++++++++++++
docs/README.md | 10 ++--
reference/subscriber.json | 20 ++++----
6 files changed, 89 insertions(+), 52 deletions(-)
rename docs/{2_Quick Reference.md => 2_Quick_Reference.md} (73%)
create mode 100644 docs/6_Callback.md
diff --git a/docs/2_Quick Reference.md b/docs/2_Quick_Reference.md
similarity index 73%
rename from docs/2_Quick Reference.md
rename to docs/2_Quick_Reference.md
index 6e8bb56a..a04e566f 100644
--- a/docs/2_Quick Reference.md
+++ b/docs/2_Quick_Reference.md
@@ -21,7 +21,7 @@ Um Ressourcen eindeutig zu identifizieren, werden in den URLs der REST Endpunkt
### Von der API bereitgestellte IDs
#### application-id
-Der Zustelldienst weist jedem übertragenen Antrag (`Application`) eine global eindeutige `application-id` zu, die diesen Antrag dauerhaft über den gesamten Bearbeitungsverlauf eindeutig identifiziert.
+Der Zustelldienst weist jedem übertragenen Antrag (`application`) eine global eindeutige `application-id` zu, die diesen Antrag dauerhaft über den gesamten Bearbeitungsverlauf eindeutig identifiziert.
#### destination-id
Die `destination-id` ist eine vom Zustelldienst vergebene ID für einen durch den Subscriber angelegten Zustellpunkt (`destination`). Diese ID wird dem Sender über externe Systeme (bspw. Zuständigkeitsfinder) oder bilaterale Absprachen zwischen beiden Seiten mitgeteilt.
@@ -41,44 +41,29 @@ Der Sender vergibt für jedes Antragsformular und jede Anlage in einer Übertrag
Mit folgenden Operationen kann der Sender eine Application übertragen und die Übertragung verwalten:
-- [Create Application](../reference/sender.json/paths/~1{source-id}~1{destination-id}/post)
-Legt eine neue Ãœbertragung an.
-- [Add Application Data](../reference/sender.json/paths/~1{source-id}~1{destination-id}~1{application-id}~1data/put)
-Fügt dem Antrag strukturierte Daten hinzu.
-- [Add Application Document](../reference/sender.json/paths/~1{source-id}~1{destination-id}~1{application-id}~1docs~1{doc-id}/put)
-Ãœbermittelt ein Antragsformular oder eine Anlage.
-- [Send Application](../reference/sender.json/paths/~1{source-id}~1{destination-id}~1{application-id}/post)
-Beendet die Übertragung des Antrags und löst seinen Versand aus.
-- [Get Application Upload Status](../reference/sender.json/paths/~1{source-id}~1{destination-id}~1{application-id}~1upload-status/get)
-Ruft den Status der Uploads der Teile der Übertragung ab. Für die Fachdaten und Dokumente wird jeweils der Status und die auf dem Server vorliegende Länge in Bytes zurückgegegben.
+- [Create Application](../reference/sender.json/paths/~1{source-id}~1{destination-id}/post) - Legt eine neue Ãœbertragung durch Ãœbermittlung der Metadaten an.
+- [Add Application Data](../reference/sender.json/paths/~1{source-id}~1{destination-id}~1{application-id}~1data/put) - Fügt dem Antrag strukturierte Daten (Fachdaten) hinzu.
+- [Add Application Document](../reference/sender.json/paths/~1{source-id}~1{destination-id}~1{application-id}~1docs~1{doc-id}/put) - Ãœbermittelt ein Antragsformular oder eine Anlage.
+- [Send Application](../reference/sender.json/paths/~1{source-id}~1{destination-id}~1{application-id}/post) - Beendet die Übertragung des Antrags und löst seinen Versand aus.
+- [Get Application Upload Status](../reference/sender.json/paths/~1{source-id}~1{destination-id}~1{application-id}~1upload-status/get) - Ruft den Status der Uploads der Teile der Übertragung ab. Für die Fachdaten und Dokumente wird jeweils der Status und die auf dem Server vorliegende Länge in Bytes zurückgegegben.
Darüber hinaus stehen dem Sender folgende weitere Operationen zur Verfügung:
-- [Get Destination](../reference/sender.json/paths/~1{source-id}~1{destination-id}/get): Ruft übertIagungsrelevante nformationen über den Zustellpunkt (bspw. zulässige Schemata oder Datentypen) ab.
-- [Get Status](../reference/sender.json/paths/~1{source-id}~1{application-id}~1status/get): Ruft den Status sowie die Statushistorie der Zustellung des Antrags ab.
+- [Get Destination](../reference/sender.json/paths/~1{source-id}~1{destination-id}/get) - Ruft übertragungsrelevante Informationen über den Zustellpunkt (bspw. zulässige Schemata oder Datentypen) ab.
+- [Get Status](../reference/sender.json/paths/~1{source-id}~1{application-id}~1status/get) - Ruft den Status sowie die Statushistorie der Zustellung des Antrags ab.
## Operation derApplication Subscriber API
Mit diesen Operationen kann der Subscriber Zustellpunkte (`Destinations`) verwalten:
-- [Create Destination](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations/post)
-Legt ein neues Ãœbertragungsziel (Destination) an.
-- [List Destinations](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations/get)
-Listet alle Ãœbertragungsziele (Destinations) eines Subscribers auf.
-- [Get Destination](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations~1{destination-id}/get)
-Ruf die Daten eines Ãœbertragungsziels (Destination) ab.
-- [Update Destination](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations~1{destination-id}/put)
-Aktualisiert ein Ãœbertragungsziel (Destination).
-- [Delete Destination](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations~1{destination-id}/delete)
-Löscht ein Übertragungsziel (Destination).
+- [Create Destination](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations/post) - Legt ein neues Ãœbertragungsziel (Destination) an.
+- [List Destinations](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations/get) - Listet alle Ãœbertragungsziele (Destinations) eines Subscribers auf.
+- [Get Destination](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations~1{destination-id}/get) - Ruf die Daten eines Ãœbertragungsziels (Destination) ab.
+- [Update Destination](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations~1{destination-id}/put) - Aktualisiert ein Ãœbertragungsziel (Destination).
+- [Delete Destination](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations~1{destination-id}/delete) - Löscht ein Übertragungsziel (Destination).
Mit diesen Operationen wird nach wartenden Applications gesucht und diese abgeholt:
-- [List Applications](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations~1{destination-id}~1applications/get)
-Ruft die Liste der wartenden Ãœbertragungen (Applications) ab.
-- [Get Application](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations~1{destination-id}~1applications~1{application-id}/get)
-Ruft eine wartende Ãœbertragung (Application) ab.
-- [Get Application Data](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations~1{destination-id}~1applications~1{application-id}~1application-data/get)
-Ruft die Fachdaten einer Ãœbertragung (Application Data) ab.
-- [Get Application Document](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations~1{destination-id}~1applications~1{application-id}~1docs~1{doc-id}/get)
-Ruf ein Dokument (Formular oder Anlage) der Application ab.
-- [Acknowledge Application](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations~1{destination-id}~1applications~1{application-id}/post)
-Quittiert die Abholung der Ãœbertragung.
+- [List Applications](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations~1{destination-id}~1applications/get) - Ruft die Liste der wartenden Ãœbertragungen (Applications) ab.
+- [Get Application](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations~1{destination-id}~1applications~1{application-id}/get) - Ruft eine wartende Ãœbertragung (Application) ab.
+- [Get Application Data](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations~1{destination-id}~1applications~1{application-id}~1application-data/get) - Ruft die Fachdaten einer Ãœbertragung (Application Data) ab.
+- [Get Application Document](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations~1{destination-id}~1applications~1{application-id}~1docs~1{doc-id}/get) - Ruf ein Dokument (Formular oder Anlage) der Application ab.
+- [Acknowledge Application](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations~1{destination-id}~1applications~1{application-id}/post) - Quittiert die Abholung der Ãœbertragung.
diff --git a/docs/3_Use_Cases_der_API.md b/docs/3_Use_Cases_der_API.md
index f709e4e2..5f5d8620 100644
--- a/docs/3_Use_Cases_der_API.md
+++ b/docs/3_Use_Cases_der_API.md
@@ -73,14 +73,14 @@ Parallelisierungspunkt innerhalb des Prozessablauf. Prozessflüsse nach dem para
**Ziel:** Ziel ist, Benachrichtigungen über abholbereite Anträge zu empfangen. Diese Benachrichtigungen ersetzen ein konstantes Polling durch den Subscriber und entlasten damit die verfügbaren Hardware und Netzwerkressourcen.
-**Beschreibung:** Bei der Benachrichtung nimmt der Subscriber die Rolle eines API Providers auf, indem dieser Benachrichtigungen empfängt. Der Zustelldienst sendet beim Vorliegen einer oder mehrer Anträge in einem Zustellpunkt an die Callback URL einen POST mit allen `application-id's` der abholbereiten Anträge.
+**Beschreibung:** Bei der Benachrichtung nimmt der Subscriber die Rolle eines API Providers auf, indem dieser Benachrichtigungen empfängt. Der Zustelldienst sendet beim Vorliegen einer oder mehrer Anträge in einem Zustellpunkt an die Callback URL einen POST mit allen `application-id`s der abholbereiten Anträge.
### Anträge abrufen
-**Vorbedingung:** Der Subscriber hat einen Zustellpunkt erstellt und einem oder mehreren Sendern die dazugehörige ´destination-id´ mitgeteilt.
+**Vorbedingung:** Der Subscriber hat einen Zustellpunkt erstellt und einem oder mehreren Sendern die dazugehörige `destination-id` mitgeteilt. Es wurde einen Antrag an eine dieser Destinations gesendet.
**Ziel:** Ziel ist es, abholbereite Anträge abzurufen.
-**Beschreibung:** Zunächst ruft der Subscriber alle Metadaten der vorliegenden Anträge. Als nächsten Schritt ruft der Subscriber die Fachdaten (`data`) sowie basierend auf den Angaben der Metadaten alle Anlagen (`document`) des Antrag ab. Falls der Subscriber den vollständigen Antrag oder alle relevanten Bestandteile abgerufen hat, bestätigt er den vollständigen Abruf. Dieser hat zur Folge, dass innerhalb einer definierten zeitlichen Frist der Antrag unwiederruflich gelöscht wird.
+**Beschreibung:** Zunächst ruft der Subscriber alle Metadaten der vorliegenden Anträge ab. Als nächsten Schritt ruft der Subscriber die Fachdaten (`data`) sowie basierend auf den Angaben der Metadaten alle Anlagen (`document`) des Antrag ab. Falls der Subscriber den vollständigen Antrag oder alle relevanten Bestandteile abgerufen hat, bestätigt er den vollständigen Abruf. Dieser hat zur Folge, dass innerhalb einer definierten zeitlichen Frist der Antrag unwiederruflich gelöscht wird.
diff --git a/docs/5_Status-_und_Fehlercodes.md b/docs/5_Status-_und_Fehlercodes.md
index b3ae3432..193f6998 100644
--- a/docs/5_Status-_und_Fehlercodes.md
+++ b/docs/5_Status-_und_Fehlercodes.md
@@ -21,6 +21,7 @@ Code | Text | Bedeutung
202 | Accepted | Daten wurden wurden erfolgreich übertragen und angenommen.
400 | Bad Request | Der Request war nicht korrekt aufgebaut oder es liegen mehrere Fehler vor, die unterschiedliche Statuscodes der 4xx-Klasse betreffen.
401 | Unauthorized | Der Request lieferte keine oder eine ungültige Authentifikation.
+ 403 | Forbidden | Die mit dem Request gelieferte Authentifikation ist für diese Resource nicht zugriffsberechtigt.
404 | Not Found | Die Ressource kann nicht unter dem angegeben Pfad gefunden werden oder temporär nicht verfügbar.
410 | Gone | Die Ressource ist unter dem Pfad permanent nicht mehr verfügbar. (bspw. weil die Ressource gelöscht wurde in dieser Repräsentation nicht mehr verfügbar ist)
413 | Request Entity Too Large | Der übertragene Datensatz ist zu groß.
@@ -29,7 +30,7 @@ Code | Text | Bedeutung
### Detailangaben zu clientseitig verursachten Fehlern
-Bei durch den API-Client verursachte Fehler (HTTP Statusklasse 4XX), liefert die API im Response Body eine [Error](../models/error.json) Mitteilung mit detaillierten Angaben, wodurch der Fehler versacht wurde.
+Bei durch den API-Client verursachte Fehler (HTTP Statusklasse 4XX), liefert die API im Response Body einen [Error Body](../models/error-body.json) Mitteilung mit detaillierten Angaben, wodurch der Fehler versacht wurde.
Eine Error Mitteilung enthält dabei folgende Angaben:
diff --git a/docs/6_Callback.md b/docs/6_Callback.md
new file mode 100644
index 00000000..ea035e5a
--- /dev/null
+++ b/docs/6_Callback.md
@@ -0,0 +1,51 @@
+# 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": {
+ "telephone": [
+ {
+ "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.
diff --git a/docs/README.md b/docs/README.md
index daec3b80..c0e13591 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -12,7 +12,7 @@ Die XFall RESTful API baut auf den bisherigen Konzepten und Erfahrungen des best
Ausgehend hiervon ist die XFall RESTful API keine einheitliche API, sondern besteht aus zwei dedizierten APIs für die Sender von Anträgen (`Application Sender API`) und die Empfänger von Anträgen (`Application Subscriber API`).
Bei der Entwicklung der XFall RESTful API wurde viele Konzepte mit Hinblick auf die neuen Erfordernisse des Onlinezugangsgesetzes, dem EU-Single Digital Gateway sowie Anforderungen moderner digitaler Geschäftsmodelle grundlegend weiterentwickelt. Im Vergleich zum bisherigen XFall-Standard setzt die XFall RESTful API auf einen leichgewichtigen REST-Architekturstil und ergänzt die API um eine einheitliche föderale Infrastruktur:
-- Eine dem "Lightweight Messagin Principle" folgende Integrationsplattform, die die APIs für die Beiteiliten anbietet und viele Integrationsherausforderungen auf beiden Seiten löst.
+- Eine dem "Lightweight Messaging Principle" folgende Integrationsplattform, die die APIs für die Beteiligten anbietet und viele Integrationsherausforderungen auf beiden Seiten löst.
- Eine zentrale Entwicklerplattform, die alle Informationen und Ressourcen für Anbindung an die XFall RESTful API bereitstellt.
### Langfristige Vision der Integrationsarchitektur
@@ -38,17 +38,17 @@ Die föderale Integrations- und Entwicklungsplattform baut auf zwei Säulen auf:
- Leichtgewichtige Schnittstellen auf Basis etablierter Industriestandards sowie zentral bereitgestellte Integrationskomponenten, um wiederkehrende Integrationsherausforderungen im verteilten föderalen Vorgehen zu lösen oder zu minimieren.
- Eine gemeinsame Entwicklerplattform und zentral bereitgestellte Entwicklungs- und Testwerkwerkzeuge, um die Entwicklung interoperabler Verfahren für die Antragsstellung und Antragsbearbeitung zu vereinfachen und zu beschleunigen. Hierbei sollen Ressourcen und Informationen zu allen gängigen föderalen Integrationsfällen und Basisdiensten für Softwareentwickler und Verfahrenverantwortliche in transparenter Weise gebündelt und zentral bereitgestellt werden.
-Die föderale Integrations- und Entwicklungsplattform folgt einem offenen Plattformgedanken und wird hiermit einen Kulturwandel in der Entwicklung digitaler Verwaltungslösungen e:nleuten
+Die föderale Integrations- und Entwicklungsplattform folgt einem offenen Plattformgedanken und wird hiermit einen Kulturwandel in der Entwicklung digitaler Verwaltungslösungen einleuten.
- Der Staat stellt eine digitale Basis an Funktionen und Daten auf Basis offener Standards und Komponenten jedem frei zur Verfügung.
-- Dies ermöglicht es allen gesellschaftlichen Akteuren (Behörden, Unternehmen, Non-Profit Organisationen, Bürger) neue digitale Lösungen und Innovationen frei erstellen.
+- Dies ermöglicht es allen gesellschaftlichen Akteuren (Behörden, Unternehmen, Non-Profit Organisationen, Bürger) neue digitale Lösungen und Innovationen frei zu erstellen.
- Entwickelte Lösungen können durch den Staat eingebunden, beauftragt oder eingekauft werden oder abseits des Staates im Rahmen neuer kommerzieller oder gesellschaftlicher Geschäftsmodelle eingebunden werden.
### Wozu dient der Proof of Concept?
-Der Proof of Concept soll wesentliche Grundprinzipien und Lösungsansätze der föderalen Integrations- und Entwicklungsplattform am Beispiel der Antragsübermittlung praktisch zu erproben. Für diesen Zweck wurde der bestehende XFall Standard für den PoC als offene RESTful-API weiterentwicklet und die dazugehörigen Integrationskomponenten und Entwicklerressourcen prototypisch bereitgestellt.
+Der Proof of Concept soll wesentliche Grundprinzipien und Lösungsansätze der föderalen Integrations- und Entwicklungsplattform am Beispiel der Antragsübermittlung praktisch zu erproben. Für diesen Zweck wurde der bestehende XFall Standard für den PoC als offene RESTful API weiterentwicklet und die dazugehörigen Integrationskomponenten und Entwicklerressourcen prototypisch bereitgestellt.
Ziel ist es aufzuzeigen, dass mit den zwei Säulen der föderalen Integrations- und Entwicklungsplattform und dem offenen Plattformansatz ein echter Mehrwert für die Entwicklung interoperabler und skalierbarer Lösungen generiert werden kann, um somit die Verwaltungsdigitalisierung in Deutschland grundlegend voranzutreiben.
-Bei einem positiven Ergebnis des Proof of Concepts wird angestrebt, die föderale Integrations- und Entwicklungsplattform als Gesamtansatz föderal umzusetzen und die XFall RESTful API sowie weitere APIs für die föderale Entwicklungsbereiche produktiv anzubieten.
\ No newline at end of file
+Bei einem positiven Ergebnis des Proof of Concepts wird angestrebt, die föderale Integrations- und Entwicklungsplattform als Gesamtansatz föderal umzusetzen und die XFall RESTful API sowie weitere APIs für die föderale Entwicklungsbereiche produktiv anzubieten.
diff --git a/reference/subscriber.json b/reference/subscriber.json
index b71852e1..0868ceb5 100644
--- a/reference/subscriber.json
+++ b/reference/subscriber.json
@@ -94,7 +94,7 @@
}
},
"403": {
- "description": "Unauthorized",
+ "description": "Forbidden",
"content": {
"application/json": {
"schema": {
@@ -213,7 +213,7 @@
}
},
"403": {
- "description": "Unauthorized",
+ "description": "Forbidden",
"content": {
"application/json": {
"schema": {
@@ -412,7 +412,7 @@
}
},
"403": {
- "description": "Unauthorized",
+ "description": "Forbidden",
"content": {
"application/json": {
"schema": {
@@ -478,7 +478,7 @@
}
},
"403": {
- "description": "Unauthorized",
+ "description": "Forbidden",
"content": {
"application/json": {
"schema": {
@@ -703,7 +703,7 @@
}
},
"403": {
- "description": "Unauthorized",
+ "description": "Forbidden",
"content": {
"application/json": {
"schema": {
@@ -831,7 +831,7 @@
}
},
"403": {
- "description": "Unauthorized",
+ "description": "Forbidden",
"content": {
"application/json": {
"schema": {
@@ -898,7 +898,7 @@
}
},
"403": {
- "description": "Unauthorized",
+ "description": "Forbidden",
"content": {
"application/json": {
"schema": {
@@ -1001,7 +1001,7 @@
}
},
"403": {
- "description": "Unauthorized",
+ "description": "Forbidden",
"content": {
"application/json": {
"schema": {
@@ -1118,7 +1118,7 @@
}
},
"403": {
- "description": "Unauthorized",
+ "description": "Forbidden",
"content": {
"application/json": {
"schema": {
@@ -1189,7 +1189,7 @@
}
},
"403": {
- "description": "Unauthorized",
+ "description": "Forbidden",
"content": {
"application/json": {
"schema": {
--
GitLab