~~NOTRANS~~
====== REST basics ======

===== Test Program =====
You can use the [[https://github.com/wiztools/rest-client|RESTClient]] to test run requests.

Firefox AddOn [[https://addons.mozilla.org/fr/firefox/addon/restclient/]]

{{:rest:rest1.png|Example request}}

===== HTTP Method =====
Have a look at the different objects on what **methods** they support.

Typically they support GET, PUT, sometimes POST and DELETE.

{{:rest:rest3.png|HTTPS Method}}

===== Return Content Type =====
==== ACCEPT ====
You can change the output format using the ''ACCEPT'' HTTP header.

=== Usage examples ===
Just add ot the the HTTP header:
{{:rest:rest4.png|REST Headers}}

=== Possible accept types ===
Supported are:
  * [[http://en.wikipedia.org/wiki/XML|XML]] (default): application/xml
  * [[http://en.wikipedia.org/wiki/JSON|JSON]]: application/json
  * [[http://www.php.net/manual/en/function.serialize.php|PHP serialized]]: application/vnd.php.serialized

==== Url Parameter ====
You can also change the output format using an URL parameter added by colon '':'' to the //method// part of the REST call.

=== Usage examples ===
  * application/json: ''/rest/projects/all:json''
  * application/xml: ''/rest/projects/all:xml''
  * application/json: ''/rest/addresses/keyword:json/__Unterm__''
  * application/xml: ''/rest/addresses/keyword:xml/__Unterm__''
  * application/xml: ''/rest/addresses/keyword/__Unterm__''

=== Possible parameters ===
Supported are:
  * xml (default): application/xml
  * json: application/json
  * serialize: application/vnd.php.serialized

===== Body =====
Body is only used for PUT and POST.

The request body has to be encoded according to [[http://en.wikipedia.org/wiki/POST_%28HTTP%29#Use_for_submitting_web_forms|application/x-www-form-urlencoded]] and the charset has to be [[http://en.wikipedia.org/wiki/UTF-8|UTF-8]]. Don't forget about the [[http://php.net/manual/en/function.urlencode.php|urlencoding]] for strings.

<WRAP group>
<WRAP half column>
{{:rest:rest5.png|REST Body}}
</WRAP>
<WRAP half column>
{{:rest:urlenc1.png?200|Add Header}}
{{:rest:urlenc2.png|REST Body}}
</WRAP>
</WRAP>


Further details on how the request body should look like can be found in the explaination of the models.

===== Authentication =====
==== Full REST user ====
The REST connection asks for an untermStrich username and password using [[http://en.wikipedia.org/wiki/Basic_access_authentication|Basic access authentication]].

**:!: You have to [[de:team:sideboard:create_rest_user|create a special "REST user"]] for these actions.**

The user has to have the right ''RESTSERVICES'' (''48'') set to ''MANAGEMENTPLUS'' (''0'').

{{:rest:rest2.png|REST Auth}}

==== Access using a standard untermStrich user ====
Some requests can be called, using a standard untermStrich user:
  - [[rest:calls|]] Either ADDRESSESANDCONTACTS or STAFFADMIN member right (For calls logging)
  - [[rest:addresses|]] Either ADDRESSESANDCONTACTS or STAFFADMIN member right (For calls logging)
  - [[rest:staff#get|Staff]] Either ADDRESSESANDCONTACTS or STAFFADMIN member right (For calls logging)
    * Only for the call ''all'', returns only 'id', 'staff_name', 'direct_dial', 'staff_location_id'

===== Errors =====
If untermStrich has to reply with an error, 
it replies with a [[wp>List of HTTP status codes|HTTP status codes]] Error (500) 
instead of OK (200).

The return body is the error message as a plain text.

===== Encoding =====
Always use [[wp>UTF-8]].

===== US-Version =====
untermStrich from X2 12.0 sends the header ''US-Version'', which allows to dedect the untermStrich version running.