Datenformate Ein- und Ausgabeformate der API

Grundlagen

Zur Kommunikation mit der API stehen verschiedene Daten-Austauschformate zur Verfügung. Bitte beachten Sie, das in allen Formaten die Variablennamen wie action, apikey usw. klein geschrieben werden müssen.

API-Anfrage

Sie können die API per Web-Request (REST bzw. POST oder GET) abfragen und die Aufrufparameter wie API-Key, action usw. als XML-Dokument, Key-/Value-Paare, JSON-Objekt oder URL-kodiert übertragen. Nutzen Sie einfach das Datenformat, mit dem Ihre Software am besten zurechtkommt. Die API erkennt das Format automatisch, Sie müssen keinen Parameter angeben.

Im folgenden Beispiel fragen wir den aktuellen Status der API ab. Dazu müssen wir der Api den Api-Key apikey, das Modul system und die action alive übergeben:

Übergeben Sie ein JSON-Objekt als String via POST oder GET aus Ihrer Software:

{
   "action" : "alive",
   "apikey" : "abcd1234",
   "modul" : "system"
}

Nutzen Sie die Punktnotation, um die Daten per POST oder GET an die API zu übertragen:

action=alive
apikey=abcd1234
modul=system

https://nettz.de/api.cgi?action=alive&apikey=abcd1234&modul=system

Übertragen Sie die Parameter per XML an die API:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<opt action="alive" apikey="abcd1234" modul="system" />

Je nach gewähltem Datenformat kann die API-Antwort auf system.alive wie folgt aussehen:

{
   "data" : {
      "version_api" : "0.9"
   },
   "status" : 1
}

data.version_api=0.9
status=1

data.version_api=0.9&status=1

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<opt status="1">
  <data version_api="0.9" />
</opt>

API-Antwort

Im Normalfall erhalten Sie die Daten von der API im selben Datenformat, in dem Sie auch Ihre Anfrage gestellt haben. Sie können mit dem Parameter options.dataformat_answer aber ein anderes Datenformat vorschreiben. Mögliche Varianten sind:

json - Die Ausgabe erfolgt im JSON-Format
xml - Sie erhalten die Daten in einem XML-Dokument
keyvalue - alle Daten werden als key=value-Paare zurückgeliefert
url - alle Daten werden URL-kodiert als Key-/Value-Paare aufgelistet

Im folgenden Beispiel fragen wir per JSON die API nach dem alive-Status und möchten die Antwort als URL-kodierten String erhalten:

{
   "action" : "alive",
   "apikey" : "abcd1234",
   "modul" : "system",
   "options" : {
	   "answer_dataformat" : "url"
   }
}

Die Antwort der API erhalten Sie dementsprechend in einem URL-kodierten Key-Value-String:

status=1&data.version_api=0.9