WebSync – REST API

— Die deutsche Version finden Sie hier —

The WebSync has a REST API interface that allows customers to manage various aspects of their series.
Besides indexing the series, selected settings of the series can be displayed and edited. This allows the customer, for example, to automatically upload new content to the sync server and then index the relevant series(es) via the REST API.

To be able to use the REST API, you must first request an API key and an API secret from Support. You must also be able to send GET and POST commands to the server using your programming language.

REST API

The base URL of the REST API is: https://websync.simsync.de/api/v1/

The endpoints are based on the following scheme: <Area>/<Action>[/<id>]?key=<api-key>[&fields=<field-list>]

Currently the following endpoints are available

Example: Show 571 series.
Endpoint: series/view/571
Full url: https://websync.simsync.de/api/v1/series/view/571?key=<use-your-key-here>

On each query or update of data, a JSON object with the following structure is returned:

{
  "success":true,
  "msg":"",
  "data": {}
}

Games

A list of the games can be found at the following endpoint: games/list?key=<api-key>
The list is built as a JSON object, where the key contains the game ID and the value contains the name of the game.

Example:
https://websync.simsync.de/api/v1/games/list?key=<use-your-key-here>

{
  "success":true,
  "msg":"",
  "data":{
    "acc":"Assetto Corsa Competizione (requires SimSync PRO 8.0.3+)",
    "actc":"ACTC Simulador de Turismo Carretera",
    "actc3":"ACTC v3 Simulador de Turismo Carretera",
    "arca":"ARCA Sim Racing",
    ...
   }
}

Series

List

Endpoint: series/list?key=<api-key>

Example:
https://websync.simsync.de/api/v1/series/list?key=<use-your-key-here>

{
  "success":true,
  "msg":"",
  "data": 
  [
    {
      "id": 8098,
      "name": "Series 1",
      "enabled": 1
    },
    {
      "id": 8298,
      "name": "Series 2",
      "enabled": 0
    },
  ]  
}

Fields

Editable fields

Edit series

While the previous two examples still worked with the HTTP GET method, all actions where data is changed, such as indexing or editing series, must be performed via HTTP POST.

The structure of the endpoints is the same as in the two previous examples: <Area>/<Action>[/<id>]?key=<api-key>. So e.g. for changing/editing the series 571: series/edit/571?key=<use-you-key-here>.
In the “body” of the POST method, the following data must be passed to the server as a URL-encoded query string, so that this way it can be ensured that the passing data really comes from the correct sender and not from a 3rd person who intercepted the API key.

data=<url-encoded data>&key=<api-key>&checksum=<url-encoded checksum>

Data is associative array (php) or an object (JS).
PHP example: $data = array('id' => 571, 'pw' => 'NewSeriesPassword', 'enabled' => 0);
JS example: var data = {'id': 571, 'pw': 'NewSeriesPassword', 'enabled': 0};

The checksum is a Sha256 hash from the following Url-encoded query:
data=<url encoded data>&key=<api-key>&secret=<api-secret>

Here is an example of how the whole thing is done in PHP:

<?php
// define url to post the data to
$url = 'https://websync.simsync.de/api/v1/series/index/571?key=<use-you-key-here>';

// Setup array for checksum 
$check = array(
  'data' => $data,
  'key' => $api_key,
  'secret' => $api_secret 
); 
// calculate sha256 checksum 
$checksum = hash('sha256', http_build_query($check), false); 

// create url-encode query string for post 
$post_data = http_build_query(
  array(
    'data' => $data,
    'key' => $api_key,
    'checksum' => $checksum
  ) 
); 

// Setup curl to send the post request 
$crl = curl_init(); 
curl_setopt($crl, CURLOPT_URL, $url); 
curl_setopt($crl, CURLOPT_POST, true); 
curl_setopt($crl, CURLOPT_POSTFIELDS, $post_data); 
curl_setopt($crl, CURLOPT_RETURNTRANSFER, true); 
curl_setopt($crl, CURLOPT_SSL_VERIFYPEER, false);  // Can/Should be true for https connections

// Post the data and get the result from the server 
$result = curl_exec($crl); 
curl_close($crl);
?>

Index series

Current indexing status

To query the current indexing status (and you should always do this BEFORE indexing), use the following endpoint via GET: series/index/<series-id>?key=<api-key>

Unless an error occurs, you will receive a response in the form:

{
  "success":true,
  "msg":"",
  "data":{
    "id":3385,
    "indexdate":"2019-10-23 13:59:54",
    "indexstatus":2,
    "indexresult":"OK"
  }
}

Index series

The indexing of a series is started by post. The endpoint for this is: /series/index/<series-id>?key=<api-key>

In the “body” of the message a string for the “changelog” must be passed, which may also be empty.

data=<url-encoded data>&key=<api-key>&checksum=<url-encoded checksum>

Data is associative array (php) or an object (JS).
PHP example: $data = array('id' => 571, 'changelog' => 'New skin added');
JS example: var data = {'id': 571, 'changelog': 'New skin added'};

The checksum is a Sha256 hash from the following Url-encoded query:
data=<url encoded data>&key=<api-key>&secret=<api-secret>

As a response you get a similar answer as when querying the index status.

{
 "success":true,
 "msg":"",
 "data":{
   "id":3385,
   "indexdate":"2019-10-23 13:59:54",
   "indexstatus":2,
   "indexresult":"OK"
 } 
}

— The english version can be found here —

Der WebSync hat eine REST API Schnittstelle, die es dem Kunden ermöglicht verschiedene Aspekte seiner Serien zu verwalten.
Neben dem Indizieren der Serien, können ausgewählte Einstellungen der Serien angezeigt und bearbeitet werden. Dadurch ist es dem Kunden z.B.  möglich, automatisiert neuen Content auf den Sync Server zu laden und die betroffene(n) Serie(n) in Anschluß per REST API to indizieren.

Um die REST API nutzen zu können, müssen Sie zuvor beim Support einen API-Key und einen API-Secret beantragen. Zudem müssen Sie in der Lage sein über Ihre Programmiersprache GET und POST Befehle an den Server zu senden.

REST API

Die Basis URL der REST API lautet: https://websync.simsync.de/api/v1/

Die Endpunkte basieren auf folgendem Schema: <Bereich>/<Aktion>[/<id>]?key=<api-key>[&fields=<field-list>]

Aktuell sind die folgenden Endpunkte verfügbar

Beispiel: Anzeige der Serie 571.
Endpunkt: series/view/571
Vollständige Url: https://websync.simsync.de/api/v1/series/view/571?key=<use-your-key-here>

Bei jeder Abfrage oder Updaten von Daten, wird ein JSON Objekt mit der folgenden Struktur zurückgegeben:

{
  "success":true,
  "msg":"",
  "data": {}
}

Spiele

Eine Liste der Spiele kann unter folgendem Endpunkt abgerufen werden: games/list?key=<api-key>
Die Liste ist als JSON Objekt aufgebaut, das der Schlüssel die Spiel ID und der Wert den jeweiligen Namen des Spiels entält.

Beispiel:
https://websync.simsync.de/api/v1/games/list?key=<use-your-key-here>

{
  "success":true,
  "msg":"",
  "data":{
    "acc":"Assetto Corsa Competizione (requires SimSync PRO 8.0.3+)",
    "actc":"ACTC Simulador de Turismo Carretera",
    "actc3":"ACTC v3 Simulador de Turismo Carretera",
    "arca":"ARCA Sim Racing",
    ...
   }
}

Serien

Auflisten

Endpunkt: series/list?key=<api-key>

Beispiel:
https://websync.simsync.de/api/v1/series/list?key=<use-your-key-here>

{
  "success":true,
  "msg":"",
  "data": 
  [
    {
      "id": 8098,
      "name": "Series 1",
      "enabled": 1
    },
    {
      "id": 8298,
      "name": "Series 2",
      "enabled": 0
    },
  ]  
}

Felder

Editierbare Felder

Serie bearbeiten

Während die beiden vorigen Beispiele noch mit der HTTP GET Methode funktioniert haben, müssen sämtliche Aktionen, bei denen Daten geändert werden, wie z.B. Serie indizieren oder bearbeiten, per HTTP POST ausgeführt werden.

Der Aufbau der Endpunkte ist dabei so wie bei den beiden vorigen Beipielen: <Bereich>/<Aktion>[/<id>]?key=<api-key>. Also z.B. für das ändern/bearbeiten der Serie 571: series/edit/571?key=<use-you-key-here>.
Im “Körper” der POST Methode müssen die folgenden Daten als URL-kodierte Abfragezeichenfolge an den Server übergeben werden, damit auf diese Weise sichergestellt werden kann, das die übergebenden Daten wirklich vom richtigen Absender kommen und nicht von einer 3. Person, die den Api-Key abgefangen hat.

data=<url-encoded data>&key=<api-key>&checksum=<url-encoded checksum>

Data ist assoziatives Array (php) oder ein Object (JS).
Beispiel PHP: $data = array('id' => 571, 'pw' => 'NewSeriesPassword', 'enabled' => 0);
Beipiel JS: var data = {'id': 571, 'pw': 'NewSeriesPassword', 'enabled': 0};

Die Checksumme ist ein Sha256 Hash aus der folgenden Url-kodierten Abfrage:
data=<url encoded data>&key=<api-key>&secret=<api-secret>

Hier ein Beispiel wie das Ganze in PHP gemacht wird:

<?php
// define url to post the data to
$url = 'https://websync.simsync.de/api/v1/series/index/571?key=<use-you-key-here>';

// Setup array for checksum 
$check = array(
  'data' => $data,
  'key' => $api_key,
  'secret' => $api_secret 
); 
// calculate sha256 checksum 
$checksum = hash('sha256', http_build_query($check), false); 

// create url-encode query string for post 
$post_data = http_build_query(
  array(
    'data' => $data,
    'key' => $api_key,
    'checksum' => $checksum
  ) 
); 

// Setup curl to send the post request 
$crl = curl_init(); 
curl_setopt($crl, CURLOPT_URL, $url); 
curl_setopt($crl, CURLOPT_POST, true); 
curl_setopt($crl, CURLOPT_POSTFIELDS, $post_data); 
curl_setopt($crl, CURLOPT_RETURNTRANSFER, true); 
curl_setopt($crl, CURLOPT_SSL_VERIFYPEER, false);  // Can/Should be true for https connections

// Post the data and get the result from the server 
$result = curl_exec($crl); 
curl_close($crl);
?>

Serie indizieren

Aktueller Indizierungsstatus

Um den aktuellen Indizierungstatus abzufragen (und das sollte man VOR dem Indizieren immer erstmal tun), verwenden sie per GET den folgenden Endpunkt: series/index/<series-id>?key=<api-key>

Sofern kein Fehler auftritt erhalten Sie eine Antwort in der Form:

{
  "success":true,
  "msg":"",
  "data":{
    "id":3385,
    "indexdate":"2019-10-23 13:59:54",
    "indexstatus":2,
    "indexresult":"OK"
  }
}

Serie indizieren

Das Indizieren einer Serie wird per Post gestartet. Der Endpunkt hierzu lautet: /series/index/<series-id>?key=<api-key>

Im “Körper” der Nachricht muss eine Zeichenfolge für den “Changelog” übergeben werden, die auch leer sein darf.

data=<url-encoded data>&key=<api-key>&checksum=<url-encoded checksum>

Data ist assoziatives Array (php) oder ein Object (JS).
Beispiel PHP: $data = array('id' => 571, 'changelog' => 'New skin added');
Beipiel JS: var data = {'id': 571, 'changelog': 'New skin added'};

Die Checksumme ist ein Sha256 Hash aus der folgenden Url-kodierten Abfrage:
data=<url encoded data>&key=<api-key>&secret=<api-secret>

Als Antwort erhält man eine ähnliche Antwort wie beim Abfragen des Index Status.

{
 "success":true,
 "msg":"",
 "data":{
   "id":3385,
   "indexdate":"2019-10-23 13:59:54",
   "indexstatus":2,
   "indexresult":"OK"
 } 
}