1. PrivateServer REST APIs
PrivateServer provides some web services in a RESTful way.
1.1. 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.
1.2. 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. PrivateServer 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)) );
PrivateServer 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 |
1.3. 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
1.4. Date-Time format
The timestamp that PrivateServer sent to the REST client must have the following format:
“YYYY-MM-DD HH:MM:SS” UTC time
2. Web Services
2.1. Account creation
HTTP POST {base request}account/create
2.1.1. 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 |
Only valid email (see RFC 2822) | (see RFC 2822) | (see RFC 2822) | ||
security_model=s | “security_model” acceptable value:
| 1 | 2 | security_model=s |
2.1.2. 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..."
}
]
}
|
2.2. Disable - enable account
HTTP POST {base request}account/status/
2.2.1. 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 PrivateWave Italia S.r.l. |
2.2.2. 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..."
}
]
}
|
2.3. Request activation link re-issue
HTTP POST {base request}account/send_configuration_link
2.3.1. 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 |
2.3.2. 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..."
}
]
}
|
2.4. List users
HTTP GET {base request}account/list
2.4.1. 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..."
}
]
}
|