WebSync – REST API

WebSync – REST API

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ältman eine Antwort wie beim Abfragen des Index Status.

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