REST APIs

provides some web services in a RESTful way.

REST Request specification

Base request url: https://server.com/rest/{api_version}/

Only HTTPS protocol is allowed.

The “api_version” is a number (integer) that specify the API version used by the client. This document is about Api version 1.

REST Request authentication

REST APIs are available under strict access contro. Users of REST APIs should have REST role (ADMIN role is not required and discouraged).

Administrator should create a specific user/password: this credential are required to authenticate REST requests. use a simplified version of Amazon S3 REST authentication protocol (http://docs.amazonwebservices.com/AmazonS3/latest/dev/RESTAuthentication.html).

For every request the REST client must calculate an HMAC-SHA1 of the request body, using the password provided. For example, using a pseudo-code:

 
Signature = Base64( HMAC-SHA1(UTF-8-Encoding-Of(<ac:macro ac:name="brand"><ac:parameter ac:name="brand">server</ac:parameter></ac:macro> Rest Password, Request body)) );

Rest password must be sent with SHA-1 hash, in HEX (lowercase) format, for example “a94a8fe5ccb19ba61c4c0873d391e987982fbbd3” for password “test”

This signature must be placed in an HTTP header named “x-privateserver-auth” with this format:

 
x-privateserver-auth = <ac:macro ac:name="brand"><ac:parameter ac:name="brand">server</ac:parameter></ac:macro> Rest username : Signature

Every request body to sign must include the Date HTTP header, as the first body line.

Request	Request body to sign	HTTP request example	Request body to sign example
HTTP POST	Date HTTP header + HTTP post request	POST /rest/1/account/ HTTP/1.1 Host: server.com Date: Tue, 27 Mar 2007 19:42:41 +0000 x-privateserver-auth: restUser:hcicpDDvL9SsO6AkvxqmIWkmOuQ= owner=Mario Rossi description=Mario Rossi personal account phone_number=%2B393334455678 email=mario.rossi@acme.com security_model=s	Tue, 27 Mar 2007 19:42:41 +0000\n owner=Mario Rossi\n description=Mario Rossi personal account\n phone_number=+393334455678\n email=mario.rossi@acme.com\n security_model=s
HTTP GET with parameters	Date HTTP header + HTTP get parameters, printed out as a list	GET /rest/1/account/?params=1&foo=3 HTTP/1.1 Host: server.com Date: Tue, 27 Mar 2007 19:42:41 +0000 x-privateserver-auth: restUser:hcicpDDvL9SsO6AkvxqmIWkmOuQ=	Tue, 27 Mar 2007 19:42:41 +0000\n params=1\n foo=3
HTTP GET without parameters	Empty string	GET /rest/1/account/ HTTP/1.1 Host: server.com Date: Tue, 27 Mar 2007 19:42:41 +0000 x-privateserver-auth: restUser:hcicpDDvL9SsO6AkvxqmIWkmOuQ=	Tue, 27 Mar 2007 19:42:41 +0000

Error response format

JSON format of error response

{
   "rest_errors": 
   [
     {
        "error_code"    : 1,
        "error_message" : "Unable to find user"
     }
     {   
        "error_code"    : 5,
        "error_message" : "Invalid email"
     }
   ]
}

Error_code: a numeric error code identifier - for future use

Error_message: a human-readable error description

Date-Time format

The timestamp that sent to the REST client must have the following format:

“YYYY-MM-DD HH:MM:SS” UTC time

Web Services

Account creation

HTTP POST {base request}account/create

HTTP POST PARAMETERS

Parameter name	Validation	Min length	Max lenght	Example
owner	Alphanumerical string with spaces and underscore - hyphen Regexp : [a-z0-9_- ]*{4,50}	4	50	owner=Mario Rossi
description	Free text	10	100	description=Mario Rossi personal account
phone_number	Phone number in international format, without spaces and brackets. The phone number must start with a “+” followed by international code and by the number. Regexp : +[0-9]*{8,20}	8	20	phone_number=+393334455678
email	Only valid email (see RFC 2822)	(see RFC 2822)	(see RFC 2822)	email=mario.rossi@acme.com
security_model=s	“security_model” acceptable value: “s” - SDES protocol “z” - ZRTP protocol “sz” - Double protocol, SDES have higher priority “zs” - Double protocol, ZRTP have higher priority	1	2	security_model=s

HTTP RESPONSE

JSON representation of user data
[MANDATORY] “provisioning_data” contain the provisioning link token and validity.

HTTP CODE

BODY

201

CREATED

All ok

{
  "owner"             : "Mario Rossi",
  "description"       : "Mario Rossi personal Account",
  "phone_number"      : "+393334455678",
  "email"             : "mario.rossi@acme.com",
  "status"            : "enabled",
  "security_model"    : "s",
  "provisioning_data" : 
  {
    "token"         : "3e29ca992780c",
    "creation_time" : "2012-01-26 18:17:48"
    "expiry_time"   : "2012-01-27 18:17:48"
  }
}

400

BAD REQUEST

Missing parameter or validation error or account already exists

{
  "rest_errors": 
  [
    { 
      "error_code"    : 5,
      "error_message" : "Invalid email"
    }
  ]
}

401

UNAUTHORIZED

Bad credential

Empty body

405

METHOD NOT ALLOWED

Not an HTTP POST

Empty body

500

INTERNAL ERROR

Server error

{
  "rest_errors":
  [
    { 
      "error_code" : 5,
      "error_message" : "Exception..."
    }
  ]
}

Disable - enable account

HTTP POST {base request}account/status/

HTTP POST PARAMETERS

Parameter name	Validation	Min length	Max lenght	Example
phone_number	Phone number in international format, without spaces and brackets. The phone number must start with a “+” followed by international code and by the number. Regexp : +[0-9]*{8,20}	8	20	phone_number=+393334455678
status	Only “disabled” or “enabled”	N.A.	N.A.	status=disabled
description	Free text	10	100	description=User doesn’t work for

HTTP RESPONSE

JSON representation of user data
[OPTIONAL] “provisioning_data” contain the provisioning link token and validity, if provisioning link is yet available

HTTP CODE

BODY

200

OK

All ok

{
  "owner"          : "Mario Rossi",
  "description"    : "Mario Rossi personal Account",
  "phone_number"   : "+393334455678",
  "email"          : "mario.rossi@p.com",
  "status"         : "disabled",
  "security_model" : "s",
}

400

BAD REQUEST

Missing paremeter or validation error

{
  "rest_errors": 
  [
    { 
      "error_code"    : 1,
      "error_message" : "no description data"
    }
  ]
}

401

UNAUTHORIZED

Bad credential

Empty body

404

NOT FOUND

User not found

Empty body

405

METHOD NOT ALLOWED

Not an HTTP POST

Empty body

500

INTERNAL ERROR

Server error

{
  "rest_errors": 
  [
    { 
      "error_code"    : 5,
      "error_message" : "Exception..."
    }
  ]
}

Request activation link re-issue

HTTP POST {base request}account/send_configuration_link

HTTP POST PARAMETERS

Parameter name

Validation

Min length

Max length

Example

phone_number

Phone number in international format, without spaces and brackets. The phone number must start with a “+” followed by international code and by the number.

Regexp : +[0-9]*{8,20}

8

20

phone_number=+393334455678

description

Free text

10

100

description=User doesn’t receive activation link

HTTP RESPONSE

JSON representation of user data
[MANDATORY] “provisioning_data” contain the new provisioning link token and validity

HTTP CODE

BODY

200

OK

All ok

{
  "owner"             : "Mario Rossi",
  "description"       : "Mario Rossi personal Account",
  "phone_number"      : "+393334455678",
  "email"             : "mario.rossi@acme.com",
  "status"            : "enabled",
  "security_model"    : "s",
  "provisioning_data" : 
  {
    "token"         : "3e29ca992780c",
    "creation_time" : "2012-01-26 18:17:48"
    "expiry_time"   : "2012-01-27 18:17:48"
   }
}

400

BAD REQUEST

Missing paremeter or validation error

{
  "rest_errors": 
  [
    { 
      "error_code"    : 1,
      "error_message" : "Invalid phone number"
    }
  ]
}

401

UNAUTHORIZED

Bad credential

Empty body

404

NOT FOUND

User not found

Empty body

405

METHOD NOT ALLOWED

Not an HTTP POST

Empty body

500

INTERNAL ERROR

Server error

{
  "rest_errors": 
  [
    { 
      "error_code"    : 5,
      "error_message" : "Exception..."
    }
  ]
}

List users

HTTP GET {base request}account/list

HTTP RESPONSE

JSON representation of user list
[OPTIONAL] “provisioning_data” contain the new provisioning link token and validity

HTTP CODE

BODY

200

OK

All ok

{
  "user_list" : 
  [
    {
      "owner" : "Mario Rossi",
      "description" : "Mario Rossi personal Account",
      "phone_number" : "+393334455678",
      "email" : "mario.rossi@acme.com",
      "status" : "enabled",
      "security_model" : "s",
      "provisioning_data" : 
      {
        "token" : "3e29ca992780c",
        "creation_time" : "2012-01-26 18:17:48"
        "expiry_time"   : "2012-01-27 18:17:48"
      }
    }
    ...
   ]
}

401

UNAUTHORIZED

Bad credential

Empty body

405

METHOD NOT ALLOWED

Not an HTTP GET

Empty body

500

INTERNAL ERROR

Server error

{
  "rest_errors": 
  [
    { 
      "error_code"    : 5,
      "error_message" : "Exception..."
    }
  ]
}