diff --git a/docs/1_Getting_Started.md b/docs/1_Getting_Started.md new file mode 100644 index 0000000000000000000000000000000000000000..ebeb96aa2cdd7a2cbc92f9a2db3d3b1063042626 --- /dev/null +++ b/docs/1_Getting_Started.md @@ -0,0 +1,3 @@ +# Erste Schritte zur API Nutzung + +Noch in Arbeit \ No newline at end of file diff --git a/docs/2_Quick Reference.md b/docs/2_Quick Reference.md new file mode 100644 index 0000000000000000000000000000000000000000..73c4f9dfa986c0bccfb2e52633966ccfed7e7e3e --- /dev/null +++ b/docs/2_Quick Reference.md @@ -0,0 +1,72 @@ +# API-Kurzreferenz + +## IDs in den XFall Endpunkten + +Um Ressourcen eindeutig zu identifizieren, werden in den URLs der REST Endpunkt eine oder mehrere Identifikatoren benutzt. + +### Durch die API bereitgestellte IDs +#### application-id +Der Zustelldienst weist jeder Übertragung (Application) eine global eindeutige `application-id` zu. + +#### destination-id +Für jeden vom Subscriber angelegtes Übertragungsziel vergibt der Zustelldienst eine global eindeutige `destination-id`. + +### Extern vergebene IDs +#### source-id +Die `source-id` ist die ID des Accounts, der die Übertragung absendet. Sie wird vom genutzten Identitätssystem vergeben und muss global eindeutig sein. + +#### subscriber-id +Die `subscriber-id` ist die ID des Accounts, der die Übertragung empfängt. Sie wird vom genutzten Identitätssystem vergeben und muss global eindeutig sein. + +### Vom Sender vergebene IDs +#### doc-id +Der Sender vergibt für jedes Antragsformular und jede Anlage in einer Übertragung eine `doc-id`. Diese muss für alle Dokumente (Antragsformulare und Anlagen) in der Übertragung eindeutig sein. Es wird empfohlen, die IDs `1`, `2` etc. zu verwenden. + +## Application Sender API +### Verwendete IDs +Es werden folgende Pfadparameter in der URL verwendet: +- `source-id`: Wird mit dem Source Account zugewiesen. +- `destination-id`: Über externes System (Zuständigkeitsfinder) dem Onlineantragsdienst bekannt. +- `application-id`: Vom Zustelldienst vergebene ID für die Übertragung. + +### Operationen +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. + +Darüber hinaus stehen dem Sender folgende weitere Operationen zur Verfügung: +- + +## Application Subscriber API + +Mit diesen Operationen werden die Abonnements (im Sinne von Destinations) des Backends/Subscribers verwaltet: +- [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. diff --git a/docs/Use Cases der API.md b/docs/3_Use_Cases_der_API.md similarity index 88% rename from docs/Use Cases der API.md rename to docs/3_Use_Cases_der_API.md index e97bded44a04f7e88c1a5bc571a3b586b88056c2..a6e2b8c58fa904f4e9a3d19643d43a54d84891fb 100644 --- a/docs/Use Cases der API.md +++ b/docs/3_Use_Cases_der_API.md @@ -1,10 +1,6 @@ -# Use Cases der XFall APIs +# Anwendungsfälle -## Überblick - -Die übergreifende Zielstellung der XFall APIs besteht darin, Anträge und Berichte, die aus den vorgelagerten Systemen (bspw. Onlineantragsdienste, Fachportal oder Berichtssysteme) in die elektronische Verfahrensbearbeitung der Verwaltung zu übergeben. - -Um diese übergreifende Zielstellung zur erfüllen, werden über die Sender-API und Subscriber-API den `Sender` (Sender eines Antrags an einen Zustellpunkt) und `Subscriber` (Empfänger eines Antrags am Zustellpunkt) von Anträge folgende Anwendungsfälle zur Verfügung gestellt: +## Überblick über die Anwendungsfälle  diff --git a/docs/4_Authentifizierung_und_Autorisierung.md b/docs/4_Authentifizierung_und_Autorisierung.md new file mode 100644 index 0000000000000000000000000000000000000000..d110a8c2b13f8912e6647a441938d9e6280a2e66 --- /dev/null +++ b/docs/4_Authentifizierung_und_Autorisierung.md @@ -0,0 +1,3 @@ +# Authentifizierung und Autorisierung + +The beginning of an awesome article... diff --git a/docs/callback.md b/docs/6_callback.md similarity index 78% rename from docs/callback.md rename to docs/6_callback.md index f241a3a49dbfd782f1edff96b5d104870ee1a4eb..ea035e5aaff78eea0bf2a57edc796c611dd6a32b 100644 --- a/docs/callback.md +++ b/docs/6_callback.md @@ -1,4 +1,9 @@ -# Callback +# 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. diff --git a/docs/7_Begrenzung_von_Abrufen.md b/docs/7_Begrenzung_von_Abrufen.md new file mode 100644 index 0000000000000000000000000000000000000000..1c5936868d0fde52014d9eda54ff6b75c7b28854 --- /dev/null +++ b/docs/7_Begrenzung_von_Abrufen.md @@ -0,0 +1,3 @@ +# Begrenzung von Abrufen + +The beginning of an awesome article... diff --git a/docs/99_Glossar.md b/docs/99_Glossar.md new file mode 100644 index 0000000000000000000000000000000000000000..1b65f89afdf063a3aa9bcc6a06d6a072a381e38b --- /dev/null +++ b/docs/99_Glossar.md @@ -0,0 +1,3 @@ +# Glossar + +The beginning of an awesome article... diff --git a/docs/README.md b/docs/README.md index 6dc3a4a69ddd0757abfc1c281b27514c852b9e1a..60d46adfbf9577a78fb1b6b278b3211b160bd99b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,8 +1,18 @@ -# FIEP PoC -## Resourcen -- [Resourcen](./resourcen.md) -- [IDs](./ids.md) - -## APIs -- [Application Sender API](./sender.md) -- [Application Subscriber API](./subscriber.md) +# Überblick über die XFall REST + +Die übergreifende Zielstellung von XFall besteht darin, Anträge und Berichte, die aus den vorgelagerten Systemen (bspw. Onlineantragsdienste, Fachportal oder Berichtssysteme) erstellt werden, in die elektronische Verfahrensbearbeitung der Verwaltung zu übergeben. + +Um diese übergreifende Zielstellung zur erfüllen, werden dem Sender eines Antrags (`Sender`) und Empfänger eines Antrags dedizierte APIs bereitgestelt, um Anträge bzw. Berichte beim XFall API-Gateway abzugeben bzw. abzuholen. + +### Welches Problem löst das XFall-Gateway bzw. die dahinliegende Integrationsinfrastruktur? + +... + +### Was bedeutet der Status "Proof of Concept"? + + +### Was ist die föderale Integrations- und Entwicklungsplattform? + + +### Überblick der Integrationsarchitektur + diff --git a/docs/ids.md b/docs/ids.md deleted file mode 100644 index 38ade9b8c84556fc4f78ce3bf16fd81847bda8f8..0000000000000000000000000000000000000000 --- a/docs/ids.md +++ /dev/null @@ -1,24 +0,0 @@ -# IDs - - - -## Extern vergebene IDs -### source-id -Die `source-id` ist die ID des Accounts, der die Übertragung absendet. Sie wird vom genutzten Identitätssystem vergeben und muss global eindeutig sein. - -### subscriber-id -Die `subscriber-id` ist die ID des Accounts, der die Übertragung empfängt. Sie wird vom genutzten Identitätssystem vergeben und muss global eindeutig sein. - -## Vom Sender vergebene IDs -### doc-id -Der Sender vergibt für jedes Antragsformular und jede Anlage in einer Übertragung eine `doc-id`. Diese muss für alle Dokumente (Antragsformulare und Anlagen) in der Übertragung eindeutig sein. Es wird empfohlen, die IDs `1`, `2` etc. zu verwenden. - -## Vom Zustelldienst vergebene IDs -### application-id -Der Zustelldienst weist jeder Übertragung (Application) eine global eindeutige `application-id` zu. - -### destination-id -Für jeden vom Subscriber angelegtes Übertragungsziel vergibt der Zustelldienst eine global eindeutige `destination-id`. - -### schema-id -Für jedes einer Destination zugeordnetes Appication Schema vergibt der Zustelldienst eine global eindeutige `schema-id`. diff --git a/docs/sender.md b/docs/sender.md deleted file mode 100644 index 4188ff8be2d7ac0023ba2fd79f975c354e3c009c..0000000000000000000000000000000000000000 --- a/docs/sender.md +++ /dev/null @@ -1,22 +0,0 @@ -# Application Sender API -## Transfer Operationen -### IDs -Es werden folgende Parameter in der URL verwendet: -- `source-id`: Wird mit dem Source Account zugewiesen. -- `destination-id`: Über externes System (Zuständigkeitsfinder) dem Onlineantragsdienst bekannt. -- `application-id`: Vom Zustelldienst vergebene ID für die Übertragung. - -### Operationen -- [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. Der Status kann folgende Werte haben: - - `missing`: Es wurden noch keine Daten hochgeladen (`length` = 0). - - `partial`: Es wurden bereits Daten hochgeladen, jedoch weniger als in den Metadaten angegeben (0 < `length` < `size` aus Metadaten). - - `complete`: Die Übertragung ist vollständig (`length` = `size` aus Metadaten). diff --git a/docs/subscriber.md b/docs/subscriber.md deleted file mode 100644 index 83b97eb37c3fbac317bb84ea73c51206ae19a292..0000000000000000000000000000000000000000 --- a/docs/subscriber.md +++ /dev/null @@ -1,27 +0,0 @@ -# Application Subscriber API -## Subscriber Operationen -### Destination Operationen -Mit diesem Satz von Operationen werden die Abonnements (Subscriptions bzw. Destinations) des Backends/Subscribers verwaltet. -- [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). - -### Application Operationen -Mit diesem Satz von Operationen wird nach wartenden Transfers/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.