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

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

{{: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}}

===== Headers =====
untermStrich supports the following headers:
==== ACCEPT ====
You can change the output format using the ''ACCEPT'' header.

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

{{:rest:rest4.png|REST Headers}}

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

{{:rest:rest5.png|REST Body}}


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

===== Authentication =====
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 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}}

===== 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 sends the header ''US-Version'', which allows to dedect the untermStrich version running.