API (Programmierschnittstelle)

Inhaltsverzeichnis

Einführung

wachstum.at bietet eine API (Programmierschnittstelle), die es erlaubt, wichtige Funktionen von wachstum.at in andere Software-Anwendungen (zB Krankenhausinformationssysteme, Praxissoftware etc.) zu integrieren. Die wichtigsten Funktionen sind dabei:

Für eine einfachere Lesbarkeit wird im Folgenden überall die vereinfachende Bezeichnung "Patient" anstelle von "Kinder, Patientinnen und Patienten) verwendet.

Die API unterstützt die Datenformate XML und JSON zur Übergabe von Messdaten eines Patienten sowie zum Abruf der daraus berechneten Parameter eines Patienten. Für beide Datenformate steht die idente Funktionalität zur Verfügung, die API-Funktionen unterscheiden sich allerdings über den URI. Im Folgenden ist die API-Funktionalität anhand des XML-Datenformats beschrieben. Für das JSON-Datenformat steht eine vollständige, interaktive Dokumentation im OpenAPI/Swagger-Format zur Verfügung.

Bitte kontaktieren Sie uns, um für den API-Zugriff freigeschalten zu werden und um Ihren API-Schlüssel zu erhalten. Loggen Sie sich dann in Folge ein, um die angezeigten Beispiele zu personalisieren und mit Ihrem konkreten API-Schlüssel anzuzeigen.

Authentifizierung

Jeder Aufruf der API muss per API-Schlüssel authentifiziert sein. Bitte registrieren Sie sich und kontaktieren Sie uns anschließend, um den Zugriff auf die API freizuschalten. Jeder registrierte Benutzer mit freigeschaltenem API-Zugriff hat einen persönlichen API-Schlüssel zur Verfügung, der über die Seite Einstellungen des entsprechenden Benutzers eingesehen werden kann.

Dieser API-Schlüssel muss bei jedem API-Aufruf übergeben werden. Dazu sind zwei Varianten möglich:

  1. Per HTTP-Header: Ihre API-Aufrufe inkludieren den HTTP-Header API-Key mit dem entsprechenden API-Schlüssel als Wert. 
    curl -X GET -H "API-Key: {API_KEY}" https://api.wachstum.at/api/xml
  2. Per Query (URL): Ihre API-Aufrufe inkludieren den Query-Parameter key mit dem entsprechenden API-Schlüssel als Wert. 
    curl -X GET https://api.wachstum.at/api/xml?key={API_KEY}

Berechnung der Parameter eines Patienten

Erlaubt die Berechnung aller Parameter eines Patienten anhand der übergebenen Messdaten. Dabei werden keinerlei Messdaten oder Parameter gespeichert, die übergebenen Messdaten werden zur einmaligen Berechnung der Parameter verwendet und dann unmittelbar verworfen. 

curl -X PUT -H "API-Key: {API_KEY}" https://api.wachstum.at/api/xml --data "@patient.xml"

wobei patient.xml diese Struktur umfasst (beispielhaft):

<?xml version="1.0"?>
<Patient xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <FirstName>Mario</FirstName>
  <LastName>Musterkind</LastName>
  <DateOfBirth>2014-06-04</DateOfBirth>
  <Gender>Male</Gender>
  <SizeFatherCm>183</SizeFatherCm>
  <SizeMotherCm>170</SizeMotherCm>
  <SizeBirthCm>9</SizeBirthCm>
  <WeightBirthG>3500</WeightBirthG>
  <WeekBirth>42</WeekBirth>
  <HeadBirthCm>40</HeadBirthCm>
  <Measurements>
    <Measurement>
      <Date>2019-05-06T00:00:00</Date>
      <AgeInYears>4.9</AgeInYears>
      <BoneAgeYears>4</BoneAgeYears>
      <SizeCm>115</SizeCm>
      <WeightKg>18</WeightKg>
      <HeadCm>30</HeadCm>
      <SeatCm>66</SeatCm>
    </Measurement>
  </Measurements>
  <Markers>
    <Marker>
      <Text>Mein Marker</Text>
      <Date>2019-05-06T00:00:00</Date>
    </Marker>
  </Markers>
</Patient>

Die Ausgabedaten entsprechen jener Datenstruktur, die auch beim manuellen Export eines Patienten über die Benutzeroberfläche zurückgegeben wird (beispielhaft): 

<?xml version="1.0" encoding="utf-8"?>
<Patient xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <FirstName>Mario</FirstName>
  <LastName>Musterkind</LastName>
  <DateOfBirth>2014-06-04T00:00:00</DateOfBirth>
  <AgeInYears>10.5</AgeInYears>
  <Gender>Male</Gender>
  <Diseases />
  <SizeFatherCm>183</SizeFatherCm>
  <SizeMotherCm>170</SizeMotherCm>
  <SizeBirthCm>9</SizeBirthCm>
  <WeightBirthG>3500</WeightBirthG>
  <WeekBirth>42</WeekBirth>
  <HeadBirthCm>40</HeadBirthCm>
  <TargetSizeCm>183</TargetSizeCm>
  <TargetSizeSds accuracy="exact">0.56</TargetSizeSds>
  <SizeFatherSds accuracy="exact">0.56</SizeFatherSds>
  <SizeMotherSds accuracy="exact">0.75</SizeMotherSds>
  <SizeBirthSds accuracy="less_or_equal">-6</SizeBirthSds>
  <WeightBirthSds accuracy="exact">-0.41</WeightBirthSds>
  <SizeBirthUndersized>true</SizeBirthUndersized>
  <validation_message severity="error" target="birth_size">Geburtslänge ist extrem niedrig und kann nicht übernommen werden.</validation_message>
  <Measurements>
    <Measurement>
      <Date>2019-05-06T00:00:00</Date>
      <BoneAgeYears>4</BoneAgeYears>
      <SizeCm>115</SizeCm>
      <WeightKg>18</WeightKg>
      <HeadCm>30</HeadCm>
      <SeatCm>66</SeatCm>
      <AgeYears>4.9</AgeYears>
      <Bmi>13.61</Bmi>
      <EquiBmi>18.1</EquiBmi>
      <LegCm>49</LegCm>
      <SeatLegRatio>1.3</SeatLegRatio>
      <SizeSds accuracy="exact">1.03</SizeSds>
      <SizeTurnerSyndromeSds />
      <SizeNoonanSyndromeSds />
      <BmiSds accuracy="exact">-1.32</BmiSds>
      <HeadSds accuracy="less_or_equal">-6</HeadSds>
      <SeatSds accuracy="exact">1.64</SeatSds>
      <LegSds accuracy="exact">0.23</LegSds>
      <SeatLegSds accuracy="exact">1.17</SeatLegSds>
      <WeightSds accuracy="exact">-0.08</WeightSds>
      <SizePercentile>84.85</SizePercentile>
      <SizeTurnerSyndromePercentile xsi:nil="true" />
      <SizeNoonanSyndromePercentile xsi:nil="true" />
      <BmiPercentile>9.34</BmiPercentile>
      <HeadPercentile>0</HeadPercentile>
      <SeatPercentile>94.95</SeatPercentile>
      <LegPercentile>59.1</LegPercentile>
      <SeatLegPercentile>87.9</SeatLegPercentile>
      <WeightPercentile>46.81</WeightPercentile>
      <validation_message severity="warning" target="head">Kopfumfang ist ungewöhnlich niedrig.</validation_message>
    </Measurement>
  </Measurements>
  <Markers>
    <Marker>
      <Text>Mein Marker</Text>
      <Date>2019-05-06T00:00:00</Date>
    </Marker>
  </Markers>
</Patient>

SD-Scores befinden sich immer im Wertebereich zwischen -6,0 und 6,0. Wenn bei besonders ungewöhnlichen Messdaten ein besonders hoher oder niedriger SD-Score berechnet wird, wird dieser trotzdem auf -6,0 bzw. 6,0 gerundet angegeben, da darüber oder darunter nicht immer zuverlässige SD-Scores berechnet werden können. Über die Information accuracy wird explizit angegeben, wenn SD-Scores entsprechend gerundet wurden.

Alle angegebenen Messdaten werden darüber hinaus automatisch auf Plausibilität validiert. Das Ergebnis dieser Validierung wird in Form von 0-n textuellen Hinweisen angegeben. Bei der Validierung wird zwischen drei verschiedenen Schweregraden (severity) unterschieden:

Berechnungen der Parameter eines Patienten mit Wachstumsstörungen

Bei Patienten mit besonderen Voraussetzungen wird für Berechnungen auf teilweise angepasste Referenzwerte zurückgegriffen. Das Vorhandensein kann in der XML-Datenstruktur angegeben werden, indem der Patient um folgende Daten ergänzt wird. 

<Patient>
[...]
<Diseases><Disease>TurnerSyndrome</Disease></Diseases>
[...]
</Patient>

Generierung von PDF oder Bild für eine Perzentilenkurve

Erlaubt die Generierung einer Perzentilenkurve des gewünschten Typs und Formats anhand der übergebenen Messdaten. Dabei werden keinerlei Messdaten oder Parameter gespeichert, die übergebenen Messdaten werden unmittelbar wieder verworfen. 

curl -X PUT -H "API-Key: {API_KEY}" https://api.wachstum.at/api/xml/chart/{TYP}/{FORMAT} --data "@patient.xml"

Der Parameter TYP steuert den Typ der Perzentilenkurve muss einen der folgenden Werte umfassen:

Der Parameter FORMAT steuert den das Datenformat des Ergebnisses und muss einen der folgenden Werte umfassen:

Zur Übergabe der Messdaten des Patienten wird die selbe Datenstruktur erwartet wie auch bei der Berechnung der Parameter.

Größe einer Perzentilenkurve steuern

Es ist außerdem möglich, die Größe des generierten Bildes zu steuern (trifft nur bei Perzentilenkurven im Bild-Format wie PNG oder JPG zu). Hier sind zwei Varianten möglich: Die Skalierung der Perzentilenkurve anhand eines Faktors ("Zoom"), oder die Angabe von Breite und Höhe in Pixeln.

Um die Skalierung einer Perzentilenkurve zu steuern, muss ein Query-Parameter scale übergeben werden. Wird dieser Parameter nicht übergeben, wird der Default-Wert 1 verwendet. 

curl -X PUT -H "API-Key: {API_KEY}" https://api.wachstum.at/api/xml/chart/{TYP}/{FORMAT}?scale=2.5 --data "@patient.xml"

Die Skalierung steuert den "Zoom" der Perzentilenkurve und dient dazu, die Perzentilenkurve als Ganzes zu vergrößern oder zu verkleinern. Üblicherweise ist die Skalierung der ideale Weg, um eine Perzentilenkurve in der gewünschten Größe zu generieren.

Anstelle der Skalierung kann die Größe der Perzentilenkurve auch explizit über Angabe von Breite und Höhe (in Pixeln) gesteuert werden. Hierfür müssen die Query-Parameter width und height angegeben werden. Werden diese Parameter nicht übergeben, wird der Default-Wert von 1000 Pixeln sowohl in der Höhe als auch der Breite angenommen. 

curl -X PUT -H "API-Key: {API_KEY}" https://api.wachstum.at/api/xml/chart/{TYP}/{FORMAT}?width=500&height=750 --data "@patient.xml"

Im Unterschied zur Skalierung wird in dieser Variante nicht die die Perzentilenkurve als Ganzes vergrößert oder verkleinert, sondern der zur Verfügung stehende Platz für die Perzentilenkurve konfiguriert. Das heißt, dass die Beschriftung der Perzentilenkurve (zB Titel) in der Größe nicht verändert wird, also beispielsweise bei sehr hoher Breite und Höhe relativ gesehen zur gesamten Perzentilenkurve sehr klein ist. Für die meisten Anwendungsfälle ist daher die Variante über die Skalierung zu bevorzugen, eine Konfiguration von Breite und Höhe macht aber beispielsweise dann Sinn, wenn das Seitenverhältnis der Perzentilenkurve angepasst werden soll.

Ausschnitt einer Perzentilenkurve steuern

Standardmäßig wird der sichtbare Bildauschnitt einer Perzentilenkurve automatisch so gewählt, dass einerseits alle Parameter des Patienten vollständig angezeigt werden können, und andererseits die Referenzwerte (Perzentilen) vollständig bis deren Ende (bei den meisten Perzentilenkurve sind Referenzdaten bis zum 19. Lebensjahr des Patienten verfügbar) angezeigt werden können. Bei Patienten, die jünger als 4 Jahre sind, werden manche Perzentilenkurven (zB Körperlänge/-größe) auf eine Anzeige bis zum 4. Lebensjahr optimiert.

In manchen Fällen kann es aber wünschenswert sein, dieses automatische Verhalten manuell zu steuern. Dafür stehen die Parameter crop_x und crop_x_at, sowie crop_y und crop_y_at zur Verfügung. Beispielsweise lässt der folgende Aufruf die Perzentilenkurve bei 15 Jahren enden, egal ob noch Parameter nach dem 15. Lebensjahr vorhanden sind: 

curl -X PUT -H "API-Key: {API_KEY}" https://api.wachstum.at/api/xml/chart/{TYP}/{FORMAT}?crop_x=true&crop_x_at=15 --data "@patient.xml"

Je nach Kombination dieser Parameter kann der Bildausschnitt der generierten Perzentilenkurve frei konfiguriert werden:

Referenzen einer Perzentilenkurve anzeigen

Jede Perzentilenkurve basiert auf bestimmten Referenzdaten. Die jeweils verwendeten Referenzdaten können in Textform direkt unterhalb der Perzentilenkurve eingeblendet werden, indem der Parameter references=true beim Abruf der Perzentilenkurve über die URL mitgegeben wird. 

curl -X PUT -H "API-Key: {API_KEY}" https://api.wachstum.at/api/xml/chart/{TYP}/{FORMAT}?references=true --data "@patient.xml"

In bestimmten Fällen kann es aber auch wünschenswert sein, die einer Perzentilenkurve zugrunde liegenden Referenzen nicht direkt in der Grafik, sondern an anderer Stelle in einer Anwendung anzuzeigen. Für diese Fälle steht eine eigene API-Funktion zur Verfügung, die die jeweils relevanten Referenzdaten einer Perzentilenkurve zurück gibt: 

curl -X PUT -H "API-Key: {API_KEY}" https://api.wachstum.at/api/xml/chart/{TYP}/references --data "@patient.xml"

Diese API-Funktion orientiert sich in ihrer Funktionsweise an der API-Funktion zum Abruf einer Perzentilenkurve. Es werden exakt die selben Parameter übergeben, als Resultat wird aber anstelle einer Grafik (Binärdaten) eine XML-Struktur zurückgegeben, die die sichtbaren Referenzdaten für die konkret übergebenen Werte in strukturierter Form umfasst: 

<?xml version="1.0" encoding="utf-8"?>
<references xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <reference>
    <x_axis_value>0</x_axis_value>
    <name>WHO (1)</name>
    <text>WHO Multicentre Growth Reference Study Group, Mercedes de Onis et al: WHO Child Growth Standards. Acta Paediatrica 95 (Suppl 450) (2006).</text>
  </reference>
  <reference>
    <x_axis_value>0</x_axis_value>
    <name>TS (2)</name>
    <text>Gabriele Häusler, Michael Schemper, Herwig Frisch, Peter Blümel, Klaus Schmitt, Engelbert Plöchl: Spontaneous growth in Turner syndrome: Evidence for a minor pubertal growth spurt. Eur J Pediatr 151: 283-287 (1992).</text>
  </reference>
  <reference>
    <x_axis_value>4</x_axis_value>
    <name>APEDÖ (3)</name>
    <text>Andreas Gleiss, Michael Lassi, Peter Blümel, Martin Borkenstein, Klaus Kapelari, Michael Schemper, Michael Mayer, Gabriele Häusler: Austrian Height and Body Proportion References for Children Aged 4 to under 19 Years. Annals of Human Biology 40(4): 324–332 (2013).</text>
  </reference>
</references>

Generierung einer Perzentilenkurve eines Patienten als PDF

Diese API-Funktion funktioniert im Prinzip genau so wie die Generierung einer Perzentilenkurve als Bild, allerdings wird eine PDF-Datei im A4-Format generiert. 

curl -X PUT -H "API-Key: {API_KEY}" https://api.wachstum.at/api/xml/chart/{TYP}/{FORMAT} --data "@patient.xml"

Der Parameter FORMAT muss dabei die folgenden Werte umfassen: