Neuerungen der Datenfelder-API im FIM Portal

In den letzten Monaten haben wir neben anderen Themen auch weiter an unserer API für den Baustein Datenfelder gearbeitet, welche insbesondere für Modellierende, IT-Dienstleister und Onlinedienst-Hersteller relevant sind. Als Ergebnis orientiert sich die API jetzt stärker an der FIM Methodik. Durch deutlich striktere Tests können nun schon beim Import mehr methodische Fehler abgefangen werden, die ansonsten in der Nachnutzung zu Problemen geführt hätten. Außerdem erlauben uns diese Änderungen, komplette Datenschemata nun noch einfacher über unsere API auszulesen.

Tests auf unerlaubte Änderungen von read-only Attributen

Dokumentsteckbriefe, Datenschemata, Datenfelder und Datenfeldgruppen enthalten mehrere Attribute, welche sich innerhalb einer Version nicht mehr nachträglich ändern dürfen. Dies betrifft insbesondere Informationen, die relevant für Inhalt und Struktur eines Datenschemas sind, wie zum Beispiel die Reihenfolge der Kindelemente oder der Datentyp eines Datenfelds. Während des Imports werden jetzt alle Daten mit einer aussagekräftigen Fehlermeldung abgelehnt, welche diese Bedingung verletzen. Dadurch können Probleme früh erkannt werden, und nachnutzende Systeme werden vor unerwarteten Änderungen geschützt.

Neue API zum Export im Format XDatenfelder

Bisher konnten nur komplette Datenschemata über unsere immutable-API ausgelesen werden. Diese Datenschemata entsprachen byte-für-byte den originalen, importieren Daten. Jeder Import erhält dabei eine eindeutige und stabile URL, mit welcher das originale Datenschema dauerhaft und unverändert abgefragt werden konnte. Auch vor dem neu implementierten Test, dass Änderungen von read-only Attributen abgelehnt werden, konnten wir so sicherstellen, dass sich die strukturellen Informationen eines Datenschemas hinter einer stabilen URL nicht ändern können.

Diese Designentscheidung verhinderte allerdings, dass Daten, die sich auch nach einer Versionierung ändern dürfen, wie zum Beispiel der Freigabestatus, in den bestehenden Datenschemata aktualisiert werden können. Dadurch wurden potenziell veraltete Informationen über die bisherige API ausgegeben.

Neben der immutable-API haben wir nun neue Endpunkte, welche eine dynamische XDatenfelder-Nachricht exportieren:

• GET /api/v1/schemas/<id>/<version>/xdf

• GET /api/v1/fields/baukasten/<id>/<version>/xdf

• GET /api/v1/groups/baukasten/<id>/<version>/xdf

Die entsprechende Route für Dokumentsteckbriefe wird von unserer API schon seit einiger Zeit unterstützt:

• GET /api/v1/document-profiles/<id>/<version>/xdf

Hier jeweils ein Beispiel der Exportrouten:

• https://fimportal.de/api/v1/schemas/S05000090/1.0/xdf

• https://fimportal.de/api/v1/fields/baukasten/F00000054/1.2/xdf

• https://fimportal.de/api/v1/groups/baukasten/G05000586/1.0/xdf

• https://fimportal.de/api/v1/document-profiles/D00000003/0.1/xdf

Diese neuen Routen haben mehrere Vorteile:

• Auch alle nachträglich veränderlichen Daten sind aktuell. Durch den strikteren Import ist trotzdem weiterhin sichergestellt, dass sich strukturelle Informationen nicht ohne eine Aktualisierung der Version ändern können.

• Es gibt nun ebenfalls Exporte für Datenfelder und Datenfeldgruppen. Damit können nun auch Baukastenelemente im XDatenfelder-Format exportiert werden. Das gilt sowohl für XDatenfelder 2.0 als auch für XDatenfelder 3.0.0. Dies war vorher nicht möglich, da wir keine XDatenfelder-Nachrichten für Datenfelder und Datenfeldgruppen beim Import erhalten.

• Die neuen Routen sind deutlich intuitiver in der Benutzung. Die Exportroute kann nun direkt auf Basis der FIM ID und Version erstellt werden, das vorherige Abfragen aller immutable URLs zu einem Datenschema entfällt komplett.

Wichtig: Da die immutable-API für Datenschemata nun technisch nicht mehr notwendig ist, wird ab dem 30.04.2025 keine immutable URL mehr für neue Uploads erstellt. Bestehende URLs bleiben weiterhin aktiv. Wir empfehlen daher, auf den neuen Endpunkt umzustellen. Dazu muss lediglich auf den neuen Endpunkt verwiesen werden, das Verhalten der neuen API ist ansonsten identisch zum bisherigen Export.

Details zu diesen und allen weiteren API Routen gibt es in unseren API Docs.

Direkte Verknüpfung zwischen Datenfeldern und Codelisten

Datenfelder, die auf eine Codeliste verweisen, haben nun auch in unserer API eine direkte Referenz auf die entsprechende Codeliste. Die Referenz enthält einen Link, unter dem die Codeliste direkt heruntergeladen werden kann. Damit können in unserer API jetzt zu jedem Datenfeld mit Codeliste bequem die zugehörigen Auswahlwerte und entsprechenden UI-Labels ausgelesen werden.

Kommende Neuerungen

Im Zuge der Migration zu XDatenfelder 3.0.0 erwarten wir in absehbarer Zukunft die Bereitstellung neuer Daten auf Basis dieser neuen Version des Standards. Unsere Erwartung ist, dass sich hier neue Anforderungen an unsere Suche und damit auch unsere API ergeben.

Außerdem arbeiten wir daran, das FIM Portal auf Basis des erhaltenen Feedbacks weiter zu verbessern. Wir freuen uns daher jederzeit über Ideen und Verbesserungsvorschläge per Mail an ticket@fimportal.de