====== 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  [[en:syces:api_hidden:rpcs| 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 [[en:syces:api_hidden:rpcs| 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'