Der DVGW pflegt das digitale Verzeichnis "Anpassungshandbuch" zur Verwaltung von Gasgeräten. Für jedes Gasgerät werden all jene Informationen verwaltet, die für die anstehende Umstellung von nieder- auf hochkalorisches Gas hilfreich sind. Dies umfasst neben Gerätename und -hersteller beispielsweise Angaben zu Leistung, Belastung, Düsen, Umbauhinweise sowie Dokumentation.
Der DVGW ermöglicht einen digitalen Zugriff auf dieses Verzeichnis über eine interoperable Datenschnittstelle. Die Schnittstelle folgt dem Representational state transfer (REST)-Programmierparadigma . Die übertragenen Daten müssen in der Auszeichnungssprache XML codiert sein und dem XML-Schema entsprechen, das von der jeweiligen Funktion des RESTful-Webservices erwartet wird. Die XML-Schemata sind in als XML Schema Definition (XSD) verfügbar.
Der RESTful-Webservice wird unter der URL
https://anpassungshandbuch.dvgw-sc.de/schnittstelle
bereitgestellt.
Für einen erfolgreichen Zugriff muss der abrufende Dienst über den Support des DVGW, Herrn Daniel Fricke, freigeschaltet werden. Hierzu wird ein API-Key erzeugt, der bei allen Schnittstelleninteraktionen übertragen werden muss. Zudem ist der Zugriff auf den Service nur von einer hinterlegten IP-Adresse aus möglich.
| HTTP-Statuscode | Bedeutung |
| 200 - OK | Die Anfrage wurde erfolgreich bearbeitet und das Ergebnis der Anfrage wird in der Antwort übertragen. |
| 202 - Accepted | Die Anfrage wurde akzeptiert, wird aber zu einem späteren Zeitpunkt ausgeführt. Das Gelingen der Anfrage kann nicht garantiert werden. Dieser Code wird beispielsweise bei der übertragung eines Vorschlags zur Neuanlage eines Gerätes übermittelt. |
| 307 - Temporary Redirect | Die Anfrage erfolgte Verwendung einer Versionskennung, daher erfolgt eine Weiterleitung auf die aktuelle Version des Webservices. |
| 400 - Bad Request | Die Anfrage-Nachricht war fehlerhaft aufgebaut, beispielsweise aufgrund der Verwendung nicht unterstützter Funktionsparameter, wie "di=123" anstelle "id=123" |
| 401 - Unauthorized | Die Anfrage kann nicht ohne gültige Authentifizierung durchgeführt werden. Dieser Statuscode weist auf einen nicht angegebenen oder falschen API-Code hin. |
| 403 - Forbidden | Die Anfrage wurde mangels Berechtigung des Clients nicht durchgeführt. Gründe hierfür liegen unter anderem in der Verwendung des Services von einer nicht registrierten IP-Adresse. |
| 401 - Unauthorized | Die Anfrage kann nicht ohne gültige Authentifizierung durchgeführt werden. Dieser Statuscode weist auf einen nicht angegebenen oder falschen API-Code hin. |
| 412 - Precondition Failed | Eine in der Anfrage übertragene Voraussetzung, beispielsweise das Fehlen eines erforderlichen Parameters, traf nicht zu. |
| 422 - Unprocessable Entity | Verarbeitung wird aufgrund semantischer Fehler abgelehnt. Dies ist der Fall, wenn die übermittelten Daten nicht dem jeweiligen XML-Schema entsprechen. |
| 500 - Internal Server Error | Unerwarteter Serverfehler |
| 501 - Not Implemented | Die Funktionalität, um die Anfrage zu bearbeiten, wird von diesem Server nicht bereitgestellt. Dies ist der Fall, wenn eine nichtexistente Funktion aufgerufen wird. |
Der RESTful-Webservice verfügt über versionierbare Schnittstellen zur Gewährleistung der Erweiterbarkeit bei gleichzeitiger Sicherstellung konsistenter Zugriffe. Der Zugriff auf die entsprechenden Versionen des Services erfolgt per Anhängen des entsprechenden Versionskürzels an die vorbeschriebe Webservice-URL. So ist ein Zugriff auf diese Version unter folgender URL möglich:
https://anpassungshandbuch.dvgw-sc.de/schnittstelle/2.6
Der Aufruf der URL liefert ein HTML-Dokument mit den wesentlichen Funktionen der Schnittstellenversion sowie Links zum Herunterladen der XML-Schemas, die zur Kommunikation mit den jeweiligen Funktionen befolgt werden müssen.
Des Weiteren ist die Schnittstellenbeschreibung im PDF-Format unter
https://anpassungshandbuch.dvgw-sc.de/schnittstelle/2.6/schnittstellenBeschreibung.pdf
aufrufbar
Die Funktion erlaubt den Abruf aller Stammdaten und aller Geräte, mit ihren jeweiligen Eigenschaften. Die Funktion akzeptiert Selektionsfilter, die folgende Abfragen ermöglichen:
Unabhängig davon, ob die Suchanfrage ein Gerät ausliefert, werden immer alle Stammdaten übertragen, um die Konsistenz zu gewährleisten.
Der Aufruf der Funktion erfolgt wie folgt:
GET holeGeraete?apikey={apikey}&suche={suchtext}&id={gereateid}&seit={datum}
Der Platzhalter {apiKey} ist mit dem zugewiesenen API-Key für jeden Aufruf zu ersetzen und ist zwingend erforderlich.
Zusätzlich kann entweder der Parameter 'suche' oder 'id' oder 'seit' angegeben werden, d.h. es darf nur einer oder keiner dieser Parameter übergeben werden.
Wird kein Parameter angegeben, werden alle in der Datenbank befindlichen Geräte zurückgegeben.
über den Platzhalter {suchtext} kann für den Filterparameter 'suche' ein beliebiger Freitext angegeben werden. In der resultierenden Geräteliste werden nur jene Geräte zurückgegeben, die diesen Text im Gerätenamen enthalten.
über den Platzhalter {geraeteid} kann für den Filterparameter 'id' ein Gerät mit der übergebenen ID angefordert werden.
über den Platzhalter {datum} kann für den Filterparameter 'seit' ein Zeitpunkt angegeben werden. Das Ergebnis umfasst sodann nur jene Geräte, die seit diesem Datum neu angelegt, geändert oder gelöscht wurden. Das Datum muss im ISO-8601-Format angegeben werden, beispielsweise "2024-01-01T13:11+02:00".
Informationen über gelöschte Geräte werden nur bei Filterung über den Parameter "Datum" ausgegeben. Es werden all jene Geräte aufgeführt, die vor dem übergebenen Datum angelegt und nach dem übergebenen Datum gelöscht wurden.
Der Server antwortet wie folgt:
HTTP/1.0 200 OK
Content-Type: text/xml
[XML-Datei gemäß des XML-Schemas 'holeGeraete.xsd']
Die Antwort liefert die Stammdaten und eine Liste von Geräten, die den angegebenen Filterparametern genügen. Außerdem kann die Antwort eine Liste von IDs von gelöschten Geräten enthalten.
Die Serverantwort ist entsprechend des unter:
https://anpassungshandbuch.dvgw-sc.de/schnittstelle/2.6/holeGeraete.xsd
abrufbaren XML-Schema formatiert.
Die 'holeGeraete.xsd' Datei verweist auf eine weitere *.xsd Datei, aufrufbar unter
https://anpassungshandbuch.dvgw-sc.de/schnittstelle/2.6/DVGW_Anpassungshandbuch_Types.xsd
Die Funktion erlaubt den Abruf aller Stammdaten und aller Geräte, mit ihren jeweiligen Eigenschaften. Im Gegensatz zu der unter 3.1 aufgeführten Schnittstelle werden hierfür zusätzlich Erfahrungswerte für Anpassungszeitpunkte in den Stammdaten mitgeliefert. Die Funktion akzeptiert Selektionsfilter, die folgende Abfragen ermöglichen:
Unabhängig davon, ob die Suchanfrage ein Gerät ausliefert, werden immer alle Stammdaten übertragen, um die Konsistenz zu gewährleisten.
Der Aufruf der Funktion erfolgt wie folgt:
GET holeGeraeteErfahrung?apikey={apikey}&suche={suchtext}&id={gereateid}&seit={datum}
Der Platzhalter {apiKey} ist mit dem zugewiesenen API-Key für jeden Aufruf zu ersetzen und ist zwingend erforderlich.
Zusätzlich kann entweder der Parameter 'suche' oder 'id' oder 'seit' angegeben werden, d.h. es darf nur einer oder keiner dieser Parameter übergeben werden.
Wird kein Parameter angegeben, werden alle in der Datenbank befindlichen Geräte zurückgegeben.
über den Platzhalter {suchtext} kann für den Filterparameter 'suche' ein beliebiger Freitext angegeben werden. In der resultierenden Geräteliste werden nur jene Geräte zurückgegeben, die diesen Text im Gerätenamen enthalten.
über den Platzhalter {geraeteid} kann für den Filterparameter 'id' ein Gerät mit der übergebenen ID angefordert werden.
über den Platzhalter {datum} kann für den Filterparameter 'seit' ein Zeitpunkt angegeben werden. Das Ergebnis umfasst sodann nur jene Geräte, die seit diesem Datum neu angelegt, geändert oder gelöscht wurden. Das Datum muss im ISO-8601-Format angegeben werden, beispielsweise "2014-10-25T13:11+02:00".
Informationen über gelöschte Geräte werden nur bei Filterung über den Parameter "Datum" ausgegeben. Es werden all jene Geräte aufgeführt, die vor dem übergebenen Datum angelegt und nach dem übergebenen Datum gelöscht wurden.
Der Server antwortet wie folgt:
HTTP/1.0 200 OK
Content-Type: text/xml
[XML-Datei gemäß des XML-Schemas 'holeGeraeteErfahrung.xsd']
Die Antwort liefert die Stammdaten und eine Liste von Geräten, die den angegebenen Filterparametern genügen. Außerdem kann die Antwort eine Liste von IDs von gelöschten Geräten enthalten.
Die Serverantwort ist entsprechend des unter:
https://anpassungshandbuch.dvgw-sc.de/schnittstelle/2.6/holeGeraeteErfahrung.xsd
abrufbaren XML-Schema formatiert.
Die 'holeGeraeteErfahrung.xsd' Datei verweist auf eine weitere *.xsd Datei, aufrufbar unter
https://anpassungshandbuch.dvgw-sc.de/schnittstelle/2.6/DVGW_Anpassungshandbuch_Types.xsd
Die schreibende Schnittstelle ermöglicht es, neue Geräte anzulegen oder bestehende Geräte zu aktualisieren.
Der Aufruf der schreibenden Schnittstelle erfolgt an den Webserver wie folgt:
POST schreibeGeraet?apikey={apikey}
Content-Type: text/xml
[XML-Datei gemäß des XML-Schemas 'schreibeGeraet.xsd']
Der Platzhalter {apiKey} ist mit dem zugewiesenen API-Key für jeden Aufruf zu ersetzen und ist zwingend erforderlich.
Im Request müssen per POST die zu übermittelnden Gerätedaten übertragen werden. Die Daten müssen entsprechend des unter
https://anpassungshandbuch.dvgw-sc.de/schnittstelle/2.6/schreibeGeraet.xsd
abrufbaren XML-Schema formatiert sein.
Die 'schreibeGeraet.xsd' Datei verweist auf eine weitere *.xsd Datei aufrufbar unter
https://anpassungshandbuch.dvgw-sc.de/schnittstelle/2.6/DVGW_Anpassungshandbuch_Types.xsd
HTTP/1.0 202 Accepted
Content-Type: text/plain
[XML-Datei gemäß des XML-Schemas 'schreibeGeraetAntwort.xsd']
Bei Erfolg liefert die Schnittstelle den HTTP-Code 202 Accepted zurück, da die Verarbeitung wegen der zu erwartenden Datenmenge und der manuellen Qualitätssicherung asynchron erfolgt.
Im Fehlerfall werden die in Abschnitt 2.1 aufgeführten Fehlercodes zurückgegeben, gefolgt von einer Fehlermeldung in Antwort-Teil. Im Erfolgsfall wird eine Transaktionsnummer zurückgegeben. Die Antwort ist gemäß folgenden Schemas formatiert:
https://anpassungshandbuch.dvgw-sc.de/schnittstelle/2.6/schreibeGeraetAntwort.xsd
Die lesende Schnittstelle ermöglicht es, Informationen über die Status der in vorheriger Schnittstelle eingereichten Rückmeldungen abzufragen.
Der Aufruf der schreibenden Schnittstelle erfolgt an den Webserver wie folgt:
GET holeFeedbackStatus?apikey={apikey}&transaktionsnummer={transaktionsnummer}
Der Platzhalter {apiKey} ist mit dem zugewiesenen API-Key für jeden Aufruf zu ersetzen und ist zwingend erforderlich. Der Paramater {transaktionsnummer} ist optional.
HTTP/1.0 200 OK Content-Type: text/xml [XML-Datei gemäß des XML-Schemas 'holeFeedbackStatus.xsd']
Die Schnittstelle liefert Informationen über angegebene oder alle Rückmeldungen in folgendem Format:
https://anpassungshandbuch.dvgw-sc.de/schnittstelle/2.6/holeFeedbackStatus.xsd