====== sendJSON(), sendPOST() und sendXML() ======

Der Befehl ''sendJSON()'' sendet eine HTTP-Anfrage an die angegebene URL und gibt die Antwort des Servers zurück.

''mixed **sendJSON**(string //URL//, array //Daten//, [array //Header//])''\\
''mixed **sendPOST**(string //URL//, array //Daten//, [array //Header//])''\\
''mixed **sendXML**(string //URL//, string //XML//, [array //Header//])''

  * //URL//\\ Die URL, an welche die HTTP-Anfrage geschickt werden soll.
  * //Daten//\\ Die Daten, welche im JSON- oder POST-Format übermittelt werden sollen.
  * //XML//\\ Ein XML-String, welcher übermittelt werden soll.
  * //Header//\\ Ein Array mit zusätzlichen HTTP-Header-Feldern.

**Warnung:** Die Anfrage wird synchron durchgeführt, das bedeutet, dass sie die Ladezeit der Fragebogen-Seite um die Zeit verzögert bis der angefragte Server eine Antwort sendet. Die Anfrage wird abgebrochen, wenn die Ladezeit mehr als 5 Sekunden in Anspruch nimmt.

**Hinweis:** Die Anzahl der Anfragen ist begrenzt (s. [[#einschraenkungen|Einschränkungen]]).


===== Rückgabewert sendJSON() =====

Wenn die Anfrage aufgrund eines Fehlers nicht verarbeitet werden konnte, wird ''false'' zurückgegeben.

Wenn die Gegenstelle eine Antwort im JSON-Format sendet, wird diese als Array zurückgegeben.

Ansonsten wird die Antwort des Servers als ''string'' zurückgegeben.
   
   
===== Rückgabewert sendPOST() =====

Wenn die Anfrage aufgrund eines Fehlers nicht verarbeitet werden konnte, wird ''false'' zurückgegeben.

Ansonsten wird die Antwort des Servers als ''string'' zurückgegeben.


===== Rückgabewert sendXML() =====

Wenn die Anfrage aufgrund eines Fehlers nicht verarbeitet werden konnte, wird ''false'' zurückgegeben.

Wenn der Server gültige XML-Daten übermittelt, werden diese dekodiert und als Array zurückgegeben, wobei jedes XML-Tag in einem Array mit den folgenden Schlüsseln repräsentiert wird:

  * string ''%%'name'%%'' -- Attribut-Name
  * array ''%%'attr'%%'' -- Attribute im XML-Tag
  * string ''%%'content'%%'' -- Eventueller Text-Inhalt des XML-Tags
  * array ''%%'children'%%'' -- Eventuelle Kind-Elemente des XML-Tags

Ansonsten wird die Antwort des Servers als ''string'' zurückgegeben.


===== Einschränkungen =====

  * In einem Befragungsprojekt können innerhalb von 24 Stunden maximal 1000 Anfragen versendet werden.
  * Innerhalb eines Interviews können maximal 20 Anfragen verschickt werden, innerhalb einer Seite maximal 2 Anfragen.
  * Es können keine Anfragen an den Befragungsserver selbst gesendet werden.


===== Beispiel =====

<code php>
$data = sendJSON('https://example.com', [
  'q' => 'reflect',
  'd' => 'SoSci Survey'
]);
debug($data);
</code>

<code php>
$data = sendJSON('https://api.openai.com/v1/chat/completions', [
    'model' => 'gpt-3.5-turbo',
    'messages' = [
        [
            'role' => 'user',
            'content' => 'Hello!'
        ]
    ]
], [
    'Authorization' =>  'Bearer 12345678990'
]);
debug($data);
</code>


===== Testen =====

Falls die Gegenstelle nicht so reagiert, wie man das erwarten würde, sollten Sie zunächst Ihre Anfrage prüfen.

SoSci Survey stellt unter [[https://www.soscisurvey.de/tools/post-monkey.php]] ein kleines Script zur Verfügung. Sie erhalten dort eine URL, an welche Sie eine Anfrage (Request) übermitteln können. Anschließend können Sie den Inhalt der Anfrage überprüfen.

Wenn die Anfrage Ihrer Meinung nach korrekt ist, sehen Sie sich die Antwort an. Am einfachsten senden Sie die Anfrage einmal über die Entwickler-Tools Ihres Browsers ([[:de:general:browser-tools]]) an die API. Alternativ können Sie den Rückgabewert der Funktion mittels ''debug()'' genauer ansehen (siehe oben).