REST API

Hier findest Du alles was nötig ist, um Deine ersten Schritte mit unserer REST API zu machen.

Authentifizierung

Die Authentifizierung läuft über einen API Token welchen Du bei uns in der Software unter API Schlüssel erstellen kannst. Bei diesen Token handelt es sich um einen JSON Web Token, daher enthält dieser im Payload einige Informationen für Dich breit auf welche noch genauer eingegangen wird.

Für jeden Dienst bei uns z.B. Amazon DE und Amazon UK benötigst Du einen eigenen API Token. Du kannst pro Dienst auch mehrere API Token haben z.B. einen für Deine WaWi und einen weiteren für ein Excel Plugin. Wir empfehlen Dir jeden Token einen eindeutigen Namen zu geben, diesen kannst Du im Payload des Token wieder finden.

Jeder API Token hat eine begrenzte Lebenszeit, diese beträgt i.d.R ein Jahr. Ist Dein Token abgelaufen, kannst Du unter unter API Schlüssel wieder einen neuen API Token erstellen. Das Ablaufdatum des Token ist im Payload unter exp als Unixzeit Angegeben und kann daher selber überprüft werden.

Der Token wird zu Authentifizierung im Request Header wie folgt übertragen Authorization: Bearer <JTW>.

Erste Schritte

Jetzt wo Du Deinen Token hast, kannst Du Deine ersten Schritte mit unserer API machen. Da unsere API Swagger nutzt können wir Deine ersten Schritte gemeinsam in der SWAGGER UI machen.

Du musst Dich nur entscheiden ob Du mit unseren Amazon RePricing: eSagu Amazon RePricing API oder unseren ebay RePricing: eSagu ebay RePricing API arbeiten möchtest.

Innerhalb der SWAGGER UI kannst Du beide APIs erforschen.
Swagger UI Amazon RePricing API

Wenn Du die SWAGGER UI geöffnet hast, klicke bitte zuerst auf Authorize und trage dort Deinen API Token unter Value: ein. Achte dabei darauf, das Du das Wort Bearer mit einem Leerzeichen dem Token voran setzt.

Sobald Du Deinen Token hinterlegt hast, navigiere zu Repricing Item wenn Du unsere Amazon RePricing API benutzt oder zu Item wenn Du unsere ebay RePricing API nutzt. Klicke dort auf /item und dann auf Try it out. Für den Anfang überspringen wir alle tollen Filter und Sortier Möglichkeiten und scrollen runter bis zum Execute Button. Mit einen Klick auf diesen Button hast Du Deine erste API Abfrage bei uns erfolgreich ausgeführt!

Ab jetzt empfehle ich Dir sich ein paar Minuten mit der SWAGGER UI auseinander zu setzten, diese Stellt Dir nicht nur eine grafische Oberfläche für unsere API bereit, sondern beinhaltet vor allem eine Dokumentation zu allen Endpunkten inklusive allen Request und Response Modellen.

Anfrage Limits

Auch unsere API verwendet Anfrage Limits, wie man möglichst selten in Berührung mit diesen Beschränkungen kommt wird im Abschnitt Best practices genauer erläutert.

Das jeweilige Limit für den entsprechenden Endpunkt sowie die noch verfügbaren Abfragen werden im Antwort Header mitgeteilt. X-RateLimit-Limit besagt wie viele Anfragen auf den Endpunkt pro Stunde ausgeführt werden können, Die noch verfügbaren Abfragen stehen im X-RateLimit-Remaining Header.

Die folgende Antwort auf die unten dargestellte Anfrage enthält die beiden oben beschriebenen Header.

$ curl -X GET -i "https://api.esagu.de/amzn/repricing/v1/price-gaps" -H "accept: application/json" -H "Authorization: Bearer <JWT>"
HTTP/1.1 200 OK
Server: nginx
Date: Tue, 28 Nov 2017 12:25:29 GMT
Content-Type: application/json;charset=utf-8
Content-Length: 3809
Connection: keep-alive
X-RateLimit-Limit: Requests per hour: 120
X-RateLimit-Remaining: Remaining requests: 117
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: X-Requested-With, Content-Type, Accept, Origin, Authorization
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS

[{"id":3278,"inserted":"2015-12-18T13:18:00+00:00","updated":"2016-02-16T13:22:53+00:00","name":"Gleichziehen","isDefaultMFN":false,"isDefaultFBA":false,"shippingIncluded":true,"priceGaps":[{"gap":0,"mode":"ABSOLUTE"}]}]

Hier eine Beispiel Antwort wenn das Anfrage Limit überschritten wurde.

HTTP/1.1 503 Service Unavailable
Server: nginx
Date: Tue, 28 Nov 2017 13:57:11 GMT
Content-Type: application/json;charset=utf-8
Content-Length: 76
Connection: keep-alive

{"message":"Rate limit, of \"120\" requests per hour, exceeded.","code":503}

Best practices

Artikeldaten holen / Pagination

Unsere ebay und Amazon RePricing APIs liefern über den Endpunkt /item jeweils bis zu 100 Artikel auf einmal zurück. Über die Query Parameter limit und offset kann so, wie innerhalb einer SQL Datenbank, die nächste "Seite" geholt werden. Unsere API antwortet jedoch wesentlich schneller wenn man auf den Parameter offset verzichtet und stattdessen by-id-greater-than benutzt. Dazu verwendet man als Wert die Artikel ID (id) des letzten Artikel aus der zuvor geladenen Seite. Die Sortierung ist standardmäßig aufsteigend nach unserer internen Artikel ID (id).

Die Anzahl aller Artikel welche den verwendeten Query Parametern bei der Abfrage entspricht steht im X-total-count Antwort Header wenn der Query Parameter count-items mit den Wert true bei der Abfrage verwendet wurde. Dieser sollte aus Performancegründen nur beim Holen der ersten Seite verwendet werden, da dieser Wert beim Anfragen von weiteren Seiten nicht ändern wird.

Werden nicht alle Daten welche die API bereitstellt wie z.B. die Liste der Mitbewerber benötigt, ist es immer der schnellere Weg eine CSV über unsere API anzufordern.

Artikeldaten bearbeiten

Über den Endpunkt /item/{itemId}/strategy lassen sich Artikeldaten wie z.B. die Preiseinstellungen bearbeiten, auch hier greifen die Anfrage Limits. Wenn Du also mehrere Tausend Artikel auf einmal bearbeiten möchtest ist ein CSV Import über unsere API oft der schnellere Weg. Alternativ kann bei unseren ebay RePricing kann eine Masseneditierung (EasyEdit e²) auch über die API ausgeführt werden.

API Client Code generieren

Wir bei eSagu können leider nicht alle Programmiersprachen, dank Swagger hast Du aber die möglichkeit einen API Client für Deine Programmiersprache selber zu generieren.

Für PHP gibt es die API Clients für unser Amazon und ebay RePricing auf GitHub zum download. Diese können über composer require e-sagu/e-bay-re-pricing-api-client-php bzw. composer require e-sagu/amzn-re-pricing-api-client-php einfach installiert werden.

Dazu musst Du zunächst Swagger Codegen installieren, wie das geht ist in dieser Installationsanleitung beschrieben. Oder Du führst folgenden Befehl aus wget https://oss.sonatype.org/content/repositories/releases/io/swagger/swagger-codegen-cli/2.2.1/swagger-codegen-cli-2.2.1.jar.

Ein Aufruf vom Swagger Codegen ohne weitere Parameter java -jar swagger-codegen-cli-2.2.1.jar liefert eine Liste der verfügbaren Sprachen.

Available languages: [android, aspnet5, async-scala, cwiki, csharp, cpprest, dart, flash, python-flask, go, groovy, java, jaxrs, jaxrs-cxf, jaxrs-resteasy, jaxrs-spec, inflector, javascript, javascript-closure-angular, jmeter, nancyfx, nodejs-server, objc, perl, php, python, qt5cpp, ruby, scala, scalatra, silex-PHP, sinatra, rails5, slim, spring, dynamic-html, html, html2, swagger, swagger-yaml, swift, tizen, typescript-angular2, typescript-angular, typescript-node, typescript-fetch, akka-scala, CsharpDotNet2, clojure, haskell, lumen, go-server]

Etwas versteckt ist auch die Hilfe zu dieser Kommandozeilen Anwendung: java -jar swagger-codegen-cli-2.2.1.jar help generate.

Möchten wir z.B. einen API Client für PHP so genügt folgender Aufruf java -jar swagger-codegen-cli-2.2.1.jar generate -i https://api.esagu.de/ebay/repricing/v1/swagger.json --invoker-package "eSagu\RePricing\V1" --api-package "eSagu\RePricing\V1\Api" --model-package "eSagu\RePricing\V1\Model" -l php -o ./src/. Welcher bewirkt, das von unserer ebay Repricing API ein PHP Client mit den folgenden Namespace eSagu\RePricing\V1 im Verzeichnis src/ erstellt wird.

Den so eben generiert PHP Client kann man sofort nach dem man sich mit dem Autoloader vom Composer herumgeschlagen hat :) ausprobieren, wie im folgenden Beispiel, welches die globalen Einstellungen lädt und ausgibt.

<?php
require_once(__DIR__ . '/vendor/autoload.php');

eSagu\RePricing\V1\Configuration::getDefaultConfiguration()->setApiKey('Authorization', 'YOUR_API_KEY');
eSagu\RePricing\V1\Configuration::getDefaultConfiguration()->setApiKeyPrefix('Authorization', 'Bearer');

try {
    $settingsApi = new eSagu\RePricing\V1\Api\SettingsApi();
    print_r($settingsApi->get());
} catch (Exception $e) {
    echo 'Exception when calling SettingsApi->get: ', $e->getMessage(), PHP_EOL;
}

Beispiele

Im nachfolgenden kommen einige Beispiele in der Verwendung unserer APIs. Die Beispiele sind in PHP geschrieben und verwenden einen unserer beiden API Clients, welche über den PHP Composer installiert werden können: composer require e-sagu/e-bay-re-pricing-api-client-php bzw. composer require e-sagu/amzn-re-pricing-api-client-php

Preisuploads abschalten/anschalten

Relativ Praxis nah, nachts um 3 macht unser z.B. Wawi immer ein großes update und wir möchten das während dieser zeit keine Preisuploads von eSagu zu Amazon durchgeführt werden.

<?php
require_once(__DIR__ . '/../vendor/autoload.php');

// Configure API key authorization: jwt
eSagu\Amzn\RePricing\V1\Configuration::getDefaultConfiguration()->setApiKey('Authorization', JWT_API_TOKEN);
eSagu\Amzn\RePricing\V1\Configuration::getDefaultConfiguration()->setApiKeyPrefix('Authorization', 'Bearer');

$repricingSettingsApi = new eSagu\Amzn\RePricing\V1\Api\RepricingSettingsApi();

try {
    $settings = $repricingSettingsApi->get();
    $settings->setUploadEnabled(!$settings->getUploadEnabled());

    $repricingSettingsApi->put($settings);

    echo "Upload enabled has been set to \"{$settings->getUploadEnabled()}\".", PHP_EOL;
} catch (Exception $e) {
    echo $e->getMessage(), PHP_EOL;
}

Preiseinstellungen anpassen

Im folgenden Beispiel werden für alle Artikel auf ebay die den Suchbegriff "FIFA" entsprechen die Preisrahmen angepasst. Preise werden von unserer API immer in Cents angegeben und übertragen, 2995 entsprechen daher € 29,95.

<?php

use eSagu\EBay\RePricing\V1\Model\RepricingItemPriceSettingsDTO;

require_once(__DIR__ . '/../vendor/autoload.php');

// Configure API key authorization: jwt
eSagu\EBay\RePricing\V1\Configuration::getDefaultConfiguration()->setApiKey('Authorization', JWT_API_TOKEN);
eSagu\EBay\RePricing\V1\Configuration::getDefaultConfiguration()->setApiKeyPrefix('Authorization', 'Bearer');

$itemApi = new eSagu\EBay\RePricing\V1\Api\ItemApi();
$itemStrategyApi = new eSagu\EBay\RePricing\V1\Api\ItemStrategyApi();

try {
    $items =  $itemApi->callList(null, null, null, null, 'FIFA');

    foreach ($items as $item) {
        $itemPriceSettings = $item->getStrategy()->getPriceSettings();
        $itemPriceSettings->setMinPrice(2995);
        $itemPriceSettings->setFixedPrice((int)(2995 + 4995) / 2);
        $itemPriceSettings->setMaxPrice(4995);
        $itemPriceSettings->setMode(RepricingItemPriceSettingsDTO::MODE_OPTIMIZATION_BEST_VISIBILITY)

        $itemStrategyApi->put($item->getId(), $item->getStrategy());

        echo "Updated item with id \"{$item->getId()}\"", PHP_EOL;
    }

} catch (Exception $e) {
    echo $e->getMessage(), PHP_EOL;
}

CSV Datei anfordern

Im folgenden Beispiel fordern wir eine CSV Datei an und warten solange bis diese den Status DONE hat um diese dann herunter zu laden.

<?php

use eSagu\Amzn\RePricing\V1\Model\RepricingCSVRequestDTO;

require_once(__DIR__ . '/../vendor/autoload.php');

// Configure API key authorization: jwt
eSagu\Amzn\RePricing\V1\Configuration::getDefaultConfiguration()->setApiKey('Authorization', JWT_API_TOKEN);
eSagu\Amzn\RePricing\V1\Configuration::getDefaultConfiguration()->setApiKeyPrefix('Authorization', 'Bearer');

$csvExportAPI = new \eSagu\Amzn\RePricing\V1\Api\RepricingCSVRequestApi();

try {
    $repricingCsvExport = (new RepricingCSVRequestDTO())
        ->setFields([
            RepricingCSVRequestDTO::FIELDS_SKU,
            RepricingCSVRequestDTO::FIELDS_ESAGU_ITEM_ID,
            RepricingCSVRequestDTO::FIELDS_MIN_PRICE,
            RepricingCSVRequestDTO::FIELDS_MAX_PRICE,
            RepricingCSVRequestDTO::FIELDS_FIXED_PRICE,
            RepricingCSVRequestDTO::FIELDS_PRICE_MODE
        ])
        ->setNumberFormat(RepricingCSVRequestDTO::NUMBER_FORMAT_CENTS);

    list($response, $statusCode, $httpHeader) = $csvExportAPI->postWithHttpInfo($repricingCsvExport);
    $csvRequestId = (int)basename($httpHeader['Location']);

    echo "The CSV request id is: $csvRequestId",  PHP_EOL;

    while (true) {
        sleep(60);

        $csvExport = $csvExportAPI->get($csvRequestId);

        if ($csvExport->getState() === RepricingCSVRequestDTO::STATE_DONE) {
            file_put_contents('/tmp/esagu-amzn-repricing.csv', fopen($csvExport->getCsvDownloadUrl(), 'r'));
            echo 'The CSV has been generated and downloaded to /tmp/esagu-amzn-repricing.csv',  PHP_EOL;

            break;
        }
    }

} catch (Exception $e) {
    echo $e->getMessage(), PHP_EOL;
}

Vielen Dank, dass Du bis hier hin gelesen hast. Ich hoffe diese paar Worte konnten Dir den Einstieg in unserer API etwas vereinfachen.