1. Hilfe-Center
  2. Entwickler
  3. Einführung in die verwendeten Technologien

Welche Begrifflichkeiten sollte ich kennen?

Wir verwenden die ProMaterial-Begriffe ProductGate, DistributionGate, BookingGate, BusinessManager und die technischen Begriffe API, GraphQL, GraphiQL, Authentifizierung, JWT, Token.

ProductGate

Im ProductGate liegen die Produktdaten der Herstellen. Die Daten fließen vom ProductGate in die DistributionGates der verkaufenden Stellen und von da weiter in die Vertriebskanäle. Sie werden wahrscheinlich keinen direkten Kontakt mit dem ProductGate und seiner API haben.

DistributionGate

Im DistributionGate liegen die Produktdaten des Händlers oder direktvertreibenden Herstellers. Vertriebskanäle werden an DistributionGates angeschlossen. Wenn Sie der Hersteller einer Software sind und über Ihre Software Bauprodukte verkaufen möchten, dann nutzen Sie vor allem die DistributionGate API.  Jeder DistributionGate wird über eine eigene URL erreicht.

Über die API können Sie:

  • Produkte suchen,
  • Eigenschaften (UniversalTypes), Bilder und Spezifikationen und
  • Preise und Verfügbarkeiten abrufen.

BookingGate

Sobald Produkte in den Warenkorb gelegt werden, kommt das BookingGate ins Spiel. Es bietet dafür andere Funktionen als das DistributionGate und wird über eine eigene URL erreicht. Die Authentifizierung am DistributionGate ist auch für das BookingGate gültig.

BusinessManager

Der BusinessManager ist die Oberfläche für unsere Kunden. Als Software-Hersteller können Sie über das Backend des BusinessManagers die mit Ihrer Software verbundenen DistributionGates abrufen.

API

Für englisch: englisch application programming interface.

Wir stellen Ihnen Schnittstellen für unsere Produkte zur Verfügung, über die Sie Daten abrufen und Funktionalitäten des Netzwerks nutzen können. Wir verwenden hier in der Regel den Begriff API.

Request

Eine Abfrage an unsere API ist ein Request, genauer gesagt ein HTTP Request . Auf einen Request erfolgt eine Antwort vom Server.

GraphQL

Für unsere API nutzen wir GraphQL als Abfragesprache. Für das ProductGate, DistributionGate, BookingGate, gibt es jeweils einen Endpunkt, über denen alle Daten abgefragt werden können. Ddamit unterscheidet sich GraphQL von REST, wo für jede Ressource ein anderer Endpunkt verwendet wird.

Die abzurufenden Daten werden Body des Request definiert. Wer sich mit relationalen Datenbanken und SQL auskennt, kann sich die Abfragesprache ein bisschen wie SQL vorstellen, wo mit JOIN Daten aus verschiedenen Tabellen zusammengeführt und mit WHERE Filterbedingungen festgelegt werden. So ermöglicht auch GraphQL das Zusammenführen und Filtern von Daten, auch bei hierarchischen Daten auf eine komfortable Art und Weise.

Dadurch, dass die genaue Struktur der Antwort vorgegeben wird, lassen sich auf einen Schlag alle benötigten Informationen zurückgeben und es werden keine unnötig großen Datenmengen übertragen.

GraphQL benötigt keine eigene Dokumentation, da die Dokumentation in der API schon enthalten ist. Sie können das browserbasierte Tool GraphiQL (man beachte das "i") verwenden oder Ihr gewohntes Werkzeug wie Postman oder Insomnia.

GraphiQL

GraphiQL ist ein browserbasiertes Tool, über welches die API verwendet werden kann. Es enthält die verfügbaren Funktionen zum Durchklicken, zeigt Fehler auf und bietet Syntaxvervollständigung.

Authentifizierung

Unsere APIs sind nicht alle öffentlich zugänglich, sondern setzen eine Authentifizierung voraus; wir möchten also wissen WER gerade die API verwenden möchte. Bei erfolgreicher Authentifizierung gibt unser Authentifizierungsserver ein Token heraus, welches bei jeder Anfrage an unsere APIs mitgegeben wird.

Token

Wir verwenden JWT Tokens: https://jwt.io/