~~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. {{:rest:rest5.png|REST Body}} {{:rest:urlenc1.png?200|Add Header}} {{:rest:urlenc2.png|REST Body}} ''Content-Type: application/x-www-form-urlencoded'' 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.