REST basics

Test Program

You can use the RESTClient to test run requests.

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

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.

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 Headers

Possible accept types

Supported are:

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 application/x-www-form-urlencoded and the charset has to be UTF-8. Don't forget about the urlencoding for strings.

REST Body

Add Header 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 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 Auth

Access using a standard untermStrich user

Some requests can be called, using a standard untermStrich user:

  1. Calls Either ADDRESSESANDCONTACTS or STAFFADMIN member right (For calls logging)
  2. Addresses Either ADDRESSESANDCONTACTS or STAFFADMIN member right (For calls logging)
  3. 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 HTTP status codes Error (500) instead of OK (200).

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

Encoding

Always use UTF-8.

US-Version

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