# Hubble Data API

Hubble Data API

# Auth Token und hubble API als Proxy

Die hubble Data API wurde mit Laravel (opens new window) erstellt und stellt der hubble PWA verschiedene Endpunkte bereit. Die eigentlichen Daten, beispielsweise Produkt Detail Informationen, haben ihren Ursprung dabei im Shopsystem. Somit dient die hubble Data API als Proxy zwischen API und PWA. Für eine erfolgreiche und sichere Kommunikation mit diesen Endpoints wird dabei die OAuth2 (opens new window) Methode verwendet:

Damit ein Request an die API erfolgreich ist, wird ein Auth Token im Request Objekt benötigt. Um ein gültiges Token von der API zu erhalten, müssen dafür Client ID und Client Secret, sogenannte Client Credentials, verwendet werden. Diese zwei Werte sollten in der .env Datei des Projektes eingetragen sein. Mehr zur korrekten Konfiguration und Verwendung von Werten aus der .env Datei unter dem Abschnitt Konfiguration.

Der erhaltene Token, wird als Bearer Authentication Token bezeichnet und ist im Response Objekt im Feld access_token enthalten. Die Implementation zum Erhalt eines Bearer Authentication Tokens und dessen Speicherung im Vuex Store State ist Teil der Middleware apiAuthenticate. Diese ist in den meisten Routen als Middleware aufgelistet und wird somit immer vor dem Rendering der jeweiligen Route ausgeführt. Dadurch können eingebundene Komponenten in subsequenten Requests den Token verwenden.

Es müssen folgende Felder in der .env Datei ausgefüllt sein, um ein Bearer Authentication Token zu erhalten:

  • Base URL
  • Endpoint
  • Client ID
  • Client Secret

Der Bearer Authentication Token ist kennzeichnendes Merkmal der Session gegenüber der API. Dieser Token ist Teil des Headers jeder API Kommunikation und dient zur Validierung der Zugriffsrechte.

TIP

Die hubble API agiert als Proxy zwischen der hubble PWA und dem Shop Backend.

# Verwendung der hubble API und des Auth Token

Dafür müssen folgende Schritte durchgeführt werden:

  • Schritt 1: Setzen des API_TYPE 's in der ~/.env:
# ~/.env
API_TYPE = 'api' 
1
2
  • Schritt 2: Eintrag der Credentials in die ~/.env
# .env
API_BASE_URL = '<API_BASE_URL>'
API_CLIENT_ID = '<CLIENT_ID>'
API_CLIENT_SECRET = '<CLIENT_SECRET>'
API_ENDPOINT_AUTH = 'oauth/token'
1
2
3
4
5

WARNING

Client-seitig erlaubte Keys müssen in der ~/nuxt.config.js auf die Whitelist gesetzt werden, damit diese zur Verfügung stehen. Zur korrekten Einrichtung sollte der Abschnitt Konfiguration referenziert werden.

  • Schritt 3 : Zur Verwendung der Felder wird process.env referenziert
// ~/modules/@hubblecommerce/hubble/core/store/modApi.js
// ...
baseUrl: process.env.API_BASE_URL,
endpoint: process.env.API_ENDPOINT_AUTH,
clientId: process.env.API_CLIENT_ID,
clientSecret: process.env.API_CLIENT_SECRET
// ...
1
2
3
4
5
6
7

Dies bedeutet, dass der Bearer Authentication Token kennzeichnendes Merkmal der Session ist. Dadurch wird ermöglicht, dass Shopbesucher Produkte dem Warenkorb beliebig hinzufügen und entfernen können, sowie die gewünschte Menge anpassen können, ohne sich dabei anmelden oder registrieren zu müssen.
Falls Shopbesucher das Browserfenster ohne eine Anmeldung oder Registrierung verlassen, bleibt der Zustand des Warenkorbs für einen bestimmten Zeitraum erhalten. Ermöglicht wird dies durch die Zwischenspeicherung im Browser per Cookies und $localForage. Dieser Mechanismus ist detailliert im Abschnitt Sessions nachlesbar.

TIP

Zur Speicherung von Cookies wird in hubble das Modul cookie-universal-nuxt (opens new window) verwendet. Für größeren Speicherbedarf, wie bei der vollständigen Erfassung des Einkaufswagens, wird das Modul localforage-nuxt (opens new window) eingesetzt.

TIP

Die Reihenfolge der Zustandsspeicherung nach Veränderung des States folgt immer demselben Schema: Ein Request an einen API Endpunkt wird über die action modApi/apiCall gemacht, welche den Bearer Authentication Token benötigt. Die jeweilige Response dazu wird im lokalen Vuex Store und anschließend ebenfalls im Browser als Cookie und per $localForage gespeichert.

// ~/modules/@hubblecommerce/hubble/core/store/api/modCart.js
// send API request to recalculate cart via shop system
// this step needs a valid Bearer Authentication Token
dispatch('recalculateCart', { order: JSON.stringify(order) })
    .then((response) => {
        // 1) store to local Vuex Store
        commit('setCart', response.order.cart);
        commit('setTotals');
        
        // 2) store via $localForage
        localStorageHelper.setCreatedAt(_.clone(state.cart), state.localStorageLifetime)
            .then((response) => {
                this.$localForage.setItem(state.cookieName, response);
            });
        
        // 3) store as cookie
        let smallCart = _.pick(state.cart, ['items_qty']);
        let _cart = getters.getCartEncoded(smallCart);
        
        this.$cookies.set(state.cookieName, _cart, {
            path: state.cookiePath,
            expires: getters.getCookieExpires
        });
    })
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
Warenkorb

# hubble Data API spezifische Store Module und Middleware

Im hubble Modul (~/modules/@hubblecommerce) existieren unter den store und middleware Ordnern jeweils der Ordner /api, der spezifische Logik im Zusammenhang mit der hubble Data API enthält. Grund für die Aufteilung in einen separaten Ordner (/api) ist der Anspruch, die Client Bundle Größen so klein wie möglich zu halten und Download- sowie Renderingzeiten zu verkürzen. Im Folgenden ist ein Ausschnitt aus dem Abschnitt State, der den Einbindungsmechanismus und die Funktionsweise erläutert:

Das hubble Modul (~/modules/@hubblecommerce) wird bei Start der Applikation ausgeführt (~/modules/@hubblecommerce/hubble/module.js) und anhand der, in der ~/.env eingetragenen, API_TYPE werden die entsprechenden Shop spezifischen Dateien aus dem Unterordner sw oder api registriert. Dadurch entfällt der Pfad Prefix für Shop spezifische Vuex Store Module, da es in der laufenden Applikation nur ein Store Modul mit dem jeweiligen Namen gibt.

Derselbe Mechanismus gilt für die Einbindung von Middleware. Somit können Komponenten, Middleware und andere Store Module nun unter alleiniger Verwendung des Modulnamen oder Namen der Middleware jene referenzieren.

# Beispiel

Zum Referenzieren von Store Modulen in Komponenten ist also trotz des Vorhandenseins von den zwei Dateien im @hubblecommerce Modul, sw/modApiCustomer.js und api/modApiCustomer.js, keine explizite Differenzierung notwendig, wie im Folgenden zu sehen ist:

// ~/components/customer/LoginForm.vue (simplified)
...mapActions({
    logIn: 'modApiCustomer/logIn' // name of module === 'modApiCustomer', name of action === 'logIn'
})
1
2
3
4