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"?>
<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>5.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>
  <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 />
      <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>
      <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:

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.

Steuerung der Größe einer Perzentilenkurve

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.