Shopware Playground Storefront API

Playground wurde eingestellt.

Die Storefront Api von Shopware bietet individuelle Möglichkeiten seinen eigenen Shop so zu gestalten wie man es möchte - und zwar vor allem mit einer großen technischer Freiheit.

Zugang

Die URL für den Storefront-API Zugriff ist von Shopware vorgegeben worden und ähnelt der Administration-URL für das Playground-Backend, nur Anstatt /admin steht dort /storefront-api. Sie lautet https://MEINEINSTANZ.pg.shopware.com/storefront-api/v1 wobei MEINEINSTANZ durch die von Shopware vorgegeben zu ersetzen ist.

Die API-URL bietet dann verschiedene Endpunkte für den Zugriff auf unterschiedliche Bereiche, z.B. Produkte aufrufen, Kategorien aufrufen etc.

Daraus ergibt sich dann eine URL wie https://MEINEINSTANZ.pg.shopware.com/storefront-api/v1/product/12345

Der API Zugriff auf den richtigen Shop innerhalb der Playground-Instanz ist durch eine API Zugangs-ID gesichert. Dieser muss bei jeder Storefront-API-Anfrage im Header Request mitgesendet werden. Diese Zugangs-ID befindert sich unter Backend -> Storefront-Api -> runterscrollen zu Optionen -> "API Zugangs-ID"

Das API Ergebnis

Um mit den folgenden Beispielen zu arbeiten müssen im Playground Backend ein paar Produkte angelegt sein. Mindestens jedoch ein Produkt. Mit der Bezeichnung "Produkte" und "Artikel" ist in dieser Anleitung das gleiche gemeint. Das zu erwartene Ergebnis bei z.B. 4 angelegten Produkten ist ein JSON Object wie folgt:

{"total": 4, 
 "data" : [
    {...},
    {...},
    {...},
    {...}
  ],
  ...
}

Für diese Anleitung ist interessant, dass der Rückgabewert der Api ein großes Object ist in dem sich zumindest "total" und "data" befindet. Das Object erkennt man an den geschweiften Klammern. Dieses "data" besteht aus einem Array, erkennbar an den eckigen Klammern, welches viele Objecte beinhaltet. Und zwar genau soviel Objecte wie es Produkte gibt. Der Wert "total" gibt das auch noch einmal wieder. Total sind es 4, also sind es auch 4 Produkte und damit 4 Data-Objecte.

Beispiel Ergebnis

Um das Ergebnis vorwegzunehmen, wie folgt soll in der Browserausgabe bei allen Beispielen im 4 angelegten Artikeln sein. Die folgenden Beispiele sind ausserdem Ideen und Appetitmacher für diverse Andockmöglichkeiten. Javascript Bibliotheken erfreuen sich immer mehr großer Beliebtheit.

<html>
<head>
    ...
</head>
<body>
  <a class="articlebox">
    <img src="https://aws......jpg">
    <span class="name">Mein Produkt 1</span>
    <span class="price">1,99 €</span>  
  </a>
  <a class="articlebox">
    <img src="https://aws......jpg">
    <span class="name">Mein Produkt 2</span>
    <span class="price">2,99 €</span>  
  </a>
  <a class="articlebox">
    <img src="https://aws......jpg">
    <span class="name">Mein Produkt 3</span>
    <span class="price">12,99 €</span>  
  </a>
  <a class="articlebox">
    <img src="https://aws......jpg">
    <span class="name">Mein Produkt 4</span>
    <span class="price">4,99 €</span>  
  </a>
</body>
</html>

Beispiel mit Javascript

Pures Javascript

var myApiData;
var request = new XMLHttpRequest();
    request.open('GET', 'https://MEIN INSTANZ.pg.shopware.com/storefront-api/v1/product', true);
    request.setRequestHeader("x-sw-access-key", "MEINE API ZUGANGS-ID");
    request.onload = function () {
        myApiData = this.response;
    };
    request.send();
};

Beispiel mit jQuery

Mit hilfe des Javascript Frameworks jQuery lassen sich einfache Anfragen (requests) an die Api von Shopware Playground stellen.

var myApiData;

$.ajax({
  dataType: "json",
  url: "https://MEIN INSTANZ.pg.shopware.com/storefront-api/v1/product",
  headers: {"x-sw-access-key":"MEINE API ZUGANGS-ID"},
  success: function(response){    
    myApiData = response;
    renderview();  //siehe folgend "Weiterverarbeitung der Daten"
  }
});

Weiterverarbeitung der Daten

Nachdem nun im oberen Beispiel das JSON Object von der API zurückgegeben wurde und in der Variable myApiData zwischengespeichert ist, wird nun für jeden Artikel der sich im Data-Array befindet eine Artikelbox angelegt. Dazu wird mit der Funktion $.each() jeder Artikel innerhalb vom "data"-Array, welches sich im JSON-Object befindet durchgegangen und ein a-Element erstellt. In diesem a-Element wird dann das Artikelbild (data.cover.media.url) als img-Element, sowie der Artikelname(data.name) und der Artikelpreis(data.price.gross) als span-Element ausgegeben. Ausserdem geben wir dem Element noch eine onclick-Funktion mit. Bei jedem Klick auf die Artikelbox wird dann in der Konsole eine Meldung ansgegeben. Zum Schluss wird jedes Element im Body-Tag ausgegeben.

function renderView(){
  $.each(myApiData.data,function(key,value){
    $("<a>",{
        class: "articlebox",
        html: $.each([
           $("<img>", {src: this.cover == null ? "./alternatives-bild.svg" : this.cover.media.url  }),
           $("<span>",{class: "name",text: this.name}),
           $("<span>",{class: "price",text: this.price.gross + " €"}),
           ], function(i,val){$(this).parent().append(val)}),
        click: function(){
          console.log("Artikelbox wurde geklickt");
        }
    }).appendTo( $("body") );
  }
}

Beispiel mit Vue.js (Runtime Only)

Hierzu muss das vue.js- und das Axion-Framework geladen sein.

new Vue({
  el: '#app',
  data: {
    results: []
  },
  mounted(){
     axios.get("https://MEIN INSTANZ.pg.shopware.com/storefront-api/v1/product", {headers: {"x-sw-access-key": "MEINE API ZUGANGS-ID"}}).then(response => {
       this.results = response.data
     })
  }
});

Weiterverarbeitung der Daten

<div id="app">
    <a class="article" v-for="(result, index) in results.data" :id=result.id>
        <img src="./method-draw-image.svg">
        <span class="name">{{ result.name }}</span>
        <span class="price">{{ result.price.gross }} €</span>
    </a>
</div>

Beispiel PHP mit cURL

<?php 
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, "https://MEIN INSTANZ.pg.shopware.com/storefront-api/v1/product");
  curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-sw-access-key:MEINE API ZUGANGS-ID"]);
  $myApiData = curl_exec($ch);
  curl_close($ch);
  var_dump(json_decode($myApiData, true));

Fehlermeldungen

Die API Zugangs-ID ist nicht oder nicht korrekt übergeben worden:

{
    "errors": [
        {
            "code": "0",
            "status": "401",
            "title":"Unauthorized",
            "detail": "Header 'x-sw-access-key' is required."
         }
     ]
}

Das Produkt oder Kategorie eine falsche ID übermittelt

{
    "errors": [
        {
            "code": "INVALID-UUID",
            "status": "400",
            "title": "Bad Request",
            "detail": "Value is not a valid UUID: BE15P1ELNUMM3R"
        }
    ]
}