Projekt

Allgemein

Profil

API

Allgemeinses

  • Es handelt sich um eine REST API
  • Die Daten werden im XML-Format übertragen
  • Andere Formate, wie beispielsweise Json auf Anfrage.
  • Die API beinhaltet ein paar wichtige Grundfunktionen, die zuverlässig funktionieren.

Aufbau der URL

Basis URLs: [RESOSURCE] kann dabei beispielsweise sein:
  • fms
  • pocsags
  • zveis

Authorisierung

Token

Es wird ein Header mit einem "Access-Token" mit dem Authentification Token eingefügt.
Das Authentification Token bekommt man, indem man oben auf das QR Symbol klickt (siehe auch QR Codes), den Link permanent freischaltet und dann den Teil der URL vor "goto" kopiert.
Beispiel: https://web.radio-operator.de/codes/338dc973eb295198213deaf76a9f0bf48cbdc39d/goto 

Access-Token: 338dc973eb295198213deaf76a9f0bf48cbdc39d

Http Basic Authorisierung

Mit dem üblichem Benutzernamen und Passwort (siehe: http://en.wikipedia.org/wiki/Basic_access_authentication)

Session Athorisierung

Hat man sich über den Browser angemeldet und ein gültiges Session Cookie, so kann auch dieses verwendet werden. Das ist praktisch, wenn man GET-Requests schnell im Browser testen möchte.

Http Methoden

GET

Liefert eine Liste von Einträgen unter der entsprechenden Ressource.

POST

Fügt neue Einträge der entsprechenden Ressource hinzu.
Hinweis: Der Content-Type header muss "application/xml" sein.

Format

Das Format bei GET requests kann man ja einfach durch ausprobieren herausfinden.
https://web.radio-operator.de/zveis.xml liefert beispielsweise so etwas wie:

<?xml version="1.0" encoding="UTF-8"?>
<zveis type="array">
  <zvei>
    <Bezeichnung>&#214;ffentlichkeitsarbeit</Bezeichnung>
    <Farbe>#FFFFFF</Farbe>
    <Meldung>Alarm</Meldung>
    <Schleife type="integer">16415</Schleife>
    <account-id type="integer">2</account-id>
    <created-at type="datetime">2014-07-21T13:35:19+02:00</created-at>
    <id type="integer">1830257</id>
    <updated-at type="datetime">2014-07-21T13:35:15+02:00</updated-at>
    <user-id type="integer">3</user-id>
  </zvei>
  <zvei>
    <Bezeichnung>Meine Schleife</Bezeichnung>
    <Farbe>#FF0000</Farbe>
    <Meldung>Alarm</Meldung>
    <Schleife type="integer">14459</Schleife>
    <account-id type="integer">2</account-id>
    <created-at type="datetime">2014-07-21T13:35:16+02:00</created-at>
    <id type="integer">1830255</id>
    <updated-at type="datetime">2014-07-21T13:35:12+02:00</updated-at>
    <user-id type="integer">3</user-id>
  </zvei>
</zveis>

Sollen Daten an ROW per POST übermittelt werden, dann ist das Format prinzipiell genauso. Es gibt die Möglichkeit einen Eintrag zu senden, oder gleich mehrere:

Ein Eintrag:

<?xml version="1.0" encoding="UTF-8"?>
<zvei>
  ...
</zvei>

Mehrere Einträge:

<?xml version="1.0" encoding="UTF-8"?>
<zveis type="array">
  <zvei>
    ...
  </zvei>
  <zvei>
    ...
  </zvei>
</zveis>

Hinweis: Die Felder id, user-id, account-id, created-at und updated-at dürfen nicht im POST enthalten sein.

Beispiel:

Ein neuer Pocsag Eintrag kann beispielsweise wie folgt erfolgen:

<?xml version="1.0" encoding="UTF-8"?>
<pocsag>
  <Bezeichnung>Test</Bezeichnung>
  <Farbe nil="true"></Farbe>
  <Funktion>A</Funktion>
  <Meldung>Dies ist ein Test</Meldung>
  <RIC>12345</RIC>
</pocsag>

Macht man dies mit dem Kommandozeilentool curl, dann sieht das so aus: (Obiges xml liegt im aktuellen verzeichnis als pocsag.xml)

curl -H "Access-Token: 338dc973eb295198213deaf76a9f0bf48cbdc39d" -H "Content-Type: application/xml" -d @pocsag.xml https://web.radio-operator.de/pocsags.xml

Beispiel mit PHP:

$request_xml = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<pocsag>
  <Bezeichnung>Test</Bezeichnung>
  <Farbe nil=\"true\"></Farbe>
  <Funktion>A</Funktion>
  <Meldung>Dies ist ein Test</Meldung>
  <RIC>12345</RIC>
</pocsag>";

$r = new HttpRequest('https://web.radio-operator.de/pocsags.xml', HttpRequest::METH_POST);
$r->addHeaders(array('Access-Token' => '338dc973eb295198213deaf76a9f0bf48cbdc39d'));
$r->setContentType('application/xml');
$r->setBody($request_xml);
try {
    echo $r->send()->getBody();
} catch (HttpException $ex) {
    echo $ex;
}