diff --git a/assets/images/api_overview/FIEP_strategic_vision.png b/assets/images/api_overview/FIEP_strategic_vision.png new file mode 100644 index 0000000000000000000000000000000000000000..41e22cbbde7f119aa257e03d7c8e0ffb6b05b533 Binary files /dev/null and b/assets/images/api_overview/FIEP_strategic_vision.png differ diff --git a/docs/2_Quick Reference.md b/docs/2_Quick Reference.md index c19d1033e2a62a64817a8b1d42b8c5587ed6b225..bf217c155308950e23bb70831ccae59a3ede7313 100644 --- a/docs/2_Quick Reference.md +++ b/docs/2_Quick Reference.md @@ -2,9 +2,9 @@ ## Der XFall Antrag - + -Der XFall Antrag ist das zentrale Element in der XFall API. Dieser besteht aus den Fachdaten (`Data`) und den beigefügten Anhängen (`document`). Der Antrag selbst wird über Metadaten beschrieben. +Der XFall Antrag (`application`) ist das zentrale Geschäftsobjekt in der XFall API. Dieser besteht aus den Fachdaten (`data`) und den beigefügten Anhängen (`document`) und wird über Metadaten beschrieben. Die Metadaten des Antrags ([Application Metadata](../models/application/metadata.json)) entsprechen dem früheren XFall-Container und enthalten allgemeine Informationen über den Antrag, die enthaltenen Fachdaten und die enthaltenen Anhänge: @@ -15,16 +15,16 @@ Die Metadaten des Antrags ([Application Metadata](../models/application/metadata Fachdaten bezeichnen in XFall im einen strukturieren Datensatz in XML oder JSON und können über ein externes Schema (bspw. aus FIM) beschrieben werden. Anhänge können entweder klassische Anhänge (bspw. Nachweise) sein oder oder eine PDF Representation des Fachantrags, falls dies aus rechtlichen oder technischen Gründen notwendig ist. -## IDs in den XFall Endpunkten +## Identifikatoren der XFall Ressourcen -Um Ressourcen eindeutig zu identifizieren, werden in den URLs der REST Endpunkt eine oder mehrere Identifikatoren benutzt. +Um Ressourcen eindeutig zu identifizieren, werden in den URLs der REST Endpunkt eine oder mehrere Identifikatoren (IDs) benutzt. ### Durch die API bereitgestellte IDs #### application-id -Der Zustelldienst weist jeder Übertragung (Application) eine global eindeutige `application-id` zu. +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 -Für jeden vom Subscriber angelegtes Übertragungsziel vergibt der Zustelldienst eine global eindeutige `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. ### Extern vergebene IDs #### source-id @@ -33,16 +33,17 @@ Die `source-id` ist die ID des Accounts, der die Übertragung absendet. Sie wird #### 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 +### Vom Sender vergebene Identifikatoren #### 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. +Der Sender vergibt für jedes Antragsformular und jede Anlage in einer Übertragung eine `doc-id`. Diese muss für alle Dokumente (PDF-Antragsformulare und beliebige 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. +- `source-id` +- `destination-id` +- `application-id` +- `doc-id` ### Operationen Mit folgenden Operationen kann der Sender eine Application übertragen und die Übertragung verwalten: @@ -60,21 +61,22 @@ Ruft den Status der Uploads der Teile der Übertragung ab. Für die Fachdaten un 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. ## Application Subscriber API ### Verwendete IDs -... - -**Noch in Arbeit** - -... +Es werden folgende Pfadparameter in der URL verwendet: +- `subscriber-id` +- `destination-id` +- `application-id` +- `doc-id` ### Operationen -Mit diesen Operationen werden die Abonnements (im Sinne von Destinations) des Backends/Subscribers verwaltet: +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) diff --git a/docs/3_Use_Cases_der_API.md b/docs/3_Use_Cases_der_API.md index 6af9afe60dcf25af1e90b7a4a1ce6010897787f0..f709e4e28c402e6f049b9819d2e8bdd487285694 100644 --- a/docs/3_Use_Cases_der_API.md +++ b/docs/3_Use_Cases_der_API.md @@ -2,7 +2,7 @@ ## Überblick über die Anwendungsfälle - + ### Legende der verwendeten BPMN Symbole bei Anwendungsfallabläufen diff --git a/docs/README.md b/docs/README.md index f4d5a9801e693204b536f0698470a5867aca0163..e44da89d5f0bcd8063de5e2fd5459111767046f8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,7 +6,7 @@ Um diese übergreifende Zielstellung zur erfüllen, werden dem Sender eines Antr Das XFall API-Gateway ist ein Teilbereich der zukünftigen föderalen Integrations- und Entwicklungsplattform und wird aktuell als Proof of Concept umgesetzt. -### Welches Problem löst das XFall-Gateway bzw. die dahinliegende Integrationsinfrastruktur? +### Welches Problem löst das XFall API-Gateway bzw. die dahinliegende Integrationsinfrastruktur? ... @@ -29,6 +29,7 @@ Beide Säulen folgen der Philosophie einer offenen Plattform und leiten einen Ku - Dies ermöglicht es allen gesellschaftlichen Akteuren (Behörden, Unternehmen, Non-Profit Organisationen, Bürger) neue digitale Lösungen und Innovationen frei erstellen. - Die Lösungen können durch den Staat eingebunden, beauftragt oder eingekauft werden oder abseits des Staats im Rahmen neuer kommerzieller oder gesellschaftlicher Geschäftsmodelle eingebunden werden. + #### Zielstellung des Proof of Concepts diff --git a/docs/resourcen.md b/docs/resourcen.md deleted file mode 100644 index e84a32bfa9e1cd8d1282d237c94079607d73739e..0000000000000000000000000000000000000000 --- a/docs/resourcen.md +++ /dev/null @@ -1,76 +0,0 @@ -# Resourcen - - - -## Primärresourcen -### [Application Metadata](../models/application/metadata.json) -Die Metadaten des Antrags (Application Metadata) entsprechen dem früheren XFall-Container und tragen allgemeine Informationen zu der Übertragung, wie -- Nachgefragte behördliche Leistung (Public Service Type) -- Antragsteller -- Hinweis auf Fachdaten und das dazugehörige Schema -- Struktur des Antrags (Liste der enthaltenen Dokumente) - -### [Destination](../models/destination.json) -Die Destination beschreibt einen technischen Übergabepunkt für Anträge. Dies kann ein Fachverfahren sein, aber auch ein zwischengeschaltetes System wie eine virtuelle Poststelle oder ein Kommunal-Gateway. - -Die Destination enthält folgende Informationen: -- Behörde -- technischen Ansprechpartner -- empfangbare Schemata -- technische Benachrichtigungsadresse (siehe [Callback](callback.md)) - -In Zukunft soll die Destination noch um Schlüssel für eine Ende-zu-Ende-Übertragung erweitert werden. - -## Subresourcen -### Application Data -Die Übertragung kann einen Fachdatensatz (Application Data) enthalten. Dieser darf im JSON oder XML Format vorliegen. - -### [Application Document](../models/application/document.json) -Einer Übertragung sind Dokumente zugeordnet. Dies sind z.B. Antragsformulare oder Anlagen. - -### [Application Schema](../models/application/schema.json) -Die Destination kann Schemata benennen, die empfangen werden können. Eine Übertragung referenziert dann eines dieser Schemata um festzulegen, welche Struktur die Fachdaten haben. - -## Datentypen -### [ID-String](../models/common/id-string.json) -Der ID-String ist ein String, der nur die Zeichen A-Z, a-z, 0-9 sowie Bindestrich (-), Unterstrich (_) und Punkt (.) enthält. -- Regex: `^[-_.A-Za-z0-9]+$` - -### [MIME-Type](../models/common/mime-type.json) -Der MIME-Type ist ein String, der dem Format der MIME-Typen entspricht. -- Regex: `^[-\w.]+/[-\w.+]+$` - -### [Phonenr](../models/common/phonenr.json) -Eine Telefonnummer im internationalen Format, z.B. "+49 89 32168-42". Muss mit einem Plus beginnen und darf danach außer Ziffern nur Leerzeichen ( ) und Bindestriche (-) enthalten. -Regex: `^\+[1-9]([ -]?[0-9]){1,14}$` - -### [Status](../models/status.json) -Der Status beschreibt den Fortschritt der Übertragung. Hierzu sind folgende Werte definiert: -- `incomplete`: Die Einlieferung von der Source hat begonnen -- `queued`: Die Übertragung wurde vollständig eingeliefert und akzeptiert -- `forwarded`: Die Übertragung an die direkt angebundene Destination wurde abgeschlossen -- `delivered`: Die Übertragung hat den vorgesehen Endpunkt erreicht - -<!-- theme: info --> -> **Hinweis:** Bei diesem Status handelt es sich um den Übermittlungsstatus vom Sender an den Subscriber. Die Statusmeldungen der Zuständigen Stelle an den Antragsteller sind davon unabhängig. - -## Modelle -### [Error](../models/error.json) -Die Klasse "Error" dient der Rückmeldung zu einer nicht erfolgreichen Operation. -Sie enthält drei Propertys: -- code: integer - Fehlercode -- msg: string - Fehlermeldung -- ref: string - Referenz auf fehlerhafte Stelle - -### [FIM-ID](../models/common/fim-id.json) -Die FIM ID besteht aus einer ID und einer Versionsnummmer. - -Beispiel für Stammdatenschema "S99000001V1.0": -```json -{"id":"S99000001","version":"1.0"} -``` -- Regex für "id": `^[DFGS]\d{8}$` -- Regex für "version": `^\d+\.\d+$` - -### [Identifier](../models/common/identifier.json) -Der Identifier ist nach dem "IdentifierType" aus der "Universal Business Language" der OASIS nachempfunden. Die eigentliche ID ist im Unterelement "id" enthalten. Die weiteren Elemente dienen der Definition des Namensraums, aus dem die ID kommt. Hier ind vor allem die `schemeID` und `schemeVersionID` interessant.