SyCes API

Requirements

Only regular clients can use the API. Furthermore you require an api-key. We will also store a default tariff and the default type of username if you specify them.

Protocol

Our SyCes-API uses the JSON-RPC protocol, version 2.0.

JSON-RPC (JavaScript Object Notation Remote Procedure Call) is a simple remote procedure call protocol encoded in JSON.

You must call the API via HTTPS.

Usage

Request

Clients need to send a request object to our server with the following properties:

jsonrpc: a string containing the JSON RPC version, currently “2.0”

method: a string with the name of the method to be invoked

params: an array of objects to be passed as parameters to the defined method

id: a unique string to match the response with the request that it is replying to

(could be a combination of sessionid + sequence)

Response

the response object contains the following properties

jsonrpc: a string containing the JSON RPC version, currently “2.0”

result: If no error occurred, the data returned by the invoked method. Else no result is sent.

error: if there was an error,a specified error code, otherwise no error is sent.

id: the id of the request it is responding to

Authentication

You need to a valid token for any api call. It can be retrieved by calling the authenticate-method.

Examples

request { “jsonrpc”: “2.0”, “method”: “authenticateByRealm”, “params”: {“api_key”: “231af78...”, “realm”: “clientdomain.de”}, “id”: 1}
result for valid credentials { “jsonrpc”: “2.0”, “result”: {“token”: “0252rkcf5jm2rop8rtbnno4og5”}, “id”: 1}
result for invalid credentials { “jsonrpc”: “2.0”, “code”: 20, “error”: {“message”: “Invalid credentials.”}, “id”: 1}

Example using curl

curl -i -k -H “Accept: application/json” -H “Content-Type: application/json” -X POST -d '{“jsonrpc”: “2.0”, “method”: “authenticateByRealm”, “params”: {“api_key”: “abc...”, “realm”: “clientdomain”}, “id”: 1}' 'https://host:port'