====== sendJSON(), sendPOST() and sendXML() ======

The comand ''sendJSON()'' sends a HTTP-request to the URL and returns the answer of the server.

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

  * //URL//\\ The URL to which the HTTP request should be sent.
  * //Daten//\\ The data which should be transmitted in JSON or POST format.
  * //XML//\\ An XML string which is to be transmitted.
  * //Header//\\ An array with additional HTTP-header-fields.

**Warning:** The request is performed synchronously, which means that it delays the loading time of the questionnaire page by the time until the requested server sends a response. The request is aborted if the loading time takes more than 5 seconds.

**Note:** The amount of requests is limited (s. [[#limitations|Limitations]]).


===== Return Value sendJSON() =====

If the request could not be processed due to an error, ''false'' is returned.

If the remote peer sends a response in JSON format, it is returned as an array.

Otherwise the answer from the server is returned as a ''string''.
   
   
===== Return Value sendPOST() =====

If the request could not be processed due to an error, ''false'' is returned.

Otherwise the answer from the server is returned as a ''string''.


===== Return Value sendXML() =====

If the request could not be processed due to an error, ''false'' is returned.

When the server submits valid XML data, it is decoded and returned as an array, where each XML tag is represented in an array with the following keys:

  * string ''%%'name'%%'' -- Attribute name
  * array ''%%'attr'%%'' -- Attributs in the XML-tag
  * string ''%%'content'%%'' -- Possible text content of the XML-tag
  * array ''%%'children'%%'' -- Possible kind-elements of the XML-tag

Otherwise the answer from the server is returned as a ''string''.


===== Limitations =====

  * In a survey project, a maximum of 1000 requests can be sent within 24 hours.
  * Within a survey, a maximum of 20 requests can be sent, within a page a maximum of 2 requests.
  * It is not possible to send requests to the survey surver itself. 


===== Example =====

<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>
===== Test =====

If the remote station does not respond as you would expect, you should first check your request.

SoSci Survey provides a small script at [[https://www.soscisurvey.de/tools/post-monkey.php]]. There you will receive a URL to which you can send a request. Then you can check the content of the request.

If you believe the request is correct, view the response. The easiest way to send the request to the API once is through your browser's developer tools ([[:en:general:browser-tools]]). Alternatively, you can take a closer look at the return value of the function using ''debug()'' (see above).