Einführung SOAP-API

REST API löst SOAP ab

Die plentymarkets SOAP API wird schrittweise durch eine moderne und umfangreichere API auf Basis von REST ersetzt. Neue plentymarkets Systeme werden ausschließlich mit der REST API ausgeliefert.

 

Einleitung

Was ist die plentymarkets-API?

Die plentymarkets-API ist die zentrale Datenschnittstelle zum automatischen Datenaustausch zwischen externen Softwarelösungen oder Plattformen und plentymarkets.

Die plentymarkets-API wurde in der Technologie SOAP entwickelt. Eine Verwendung ist somit mit allen modernen Hochsprachen möglich.

Erfahren Sie mehr über die plentymarkets SOAP API im folgenden Videotutorial:

Quellcode-Beispiele

Im Handbuch finden Sie Quellcode-Beispiele für die folgenden Sprachen: PHP, Java, C# und Visual Basic.

Informieren Sie sich zuerst
Der Entwurf eines soliden SOAP-Clients ist keine sehr einfache Herausforderung. Arbeiten Sie vorher diese Handbuchseite sowie alle weiteren relevanten Seiten dieses Bereichs aufmerksam durch und starten Sie erst danach mit der Planung und Umsetzung. Nur so ist gewährleistet, dass Sie alle nötigen Aspekte berücksichtigen und die richtigen SOAP-Calls verwenden.

Zielgruppe und Voraussetzungen

Wer bereits erste Erfahrungen mit dem Thema SOAP-Entwicklung gesammelt hat, wird mir zustimmen, dass für dieses Thema fundierte Kenntnisse im Bereich Objektorientierte Programmierung (OOP) und Softwaredesign zwingend nötig sind.

Wer lediglich über Grundkenntnisse verfügt und noch keine fundierte Erfahrung mit dem Entwurf und der Umsetzung von Software-Applikationen hat, wird ohne fachkundige Unterstützung nicht dazu in der Lage sein, einen soliden SOAP-Client für einen komplexen Datenaustausch über unterschiedliche Datentypen zu entwickeln. Wir haben in der Vergangenheit verschiedenste technische Anfragen bearbeitet und stellten dabei fest, dass die Ursache für Fehler und damit verbundenen Support-Anfragen im Regelfall in einem deutlichen Wissensdefizit begründet ist. Daher wird die Beantwortung von Anfragen beim Support auf solche Anwender beschränkt, die alle nötigen Informationen liefern und offensichtlich die verwendete Softwaretechnologie voll beherrschen.

Wir verfügen über ein Netzwerk an Entwicklern und Softwareunternehmen, die individuelle Integrationen vornehmen können. Wir bieten darüber hinaus auch eine Beratungsdienstleistung an, wobei Sie Ihr Integrationskonzept einen Tag lang mit einem Entwickler in unserem Haus erörtern können. Als Ergebnis der Beratung stellen wir Ihnen eine optimale Auswahl der zu verwendenden API-Calls und wichtige Hinweise zur SOAP-Client Architektur vor.

Entwicklungszyklus

Die plentymarkets SOAP-API wird zwar parallel zu plentymarkets weiterentwickelt, der Lebenszyklus weicht aber von den plentymarkets-Versionen wie folgt ab:

Eine plentymarkets SOAP-Version hat eine Lebensdauer von etwa 12 Monaten. Während dieser Zeit können Sie somit Ihre plentymarkets-Version wechseln, ohne die Implementierung Ihres SOAP-Clients zu verändern.

Tipp: SOAP-Client umstellen
Sie sollten rechtzeitig Ihren SOAP-Client auf die dann aktuelle plentymarkets SOAP-Version umstellen. Dieser Prozess ist mit einem Quellcode-Generator eine sehr einfache Aufgabe.
Kopieren Sie die neue URL des WSDL-Dokuments der neusten SOAP-Version im Menü Einstellungen » Grundeinstellungen » API-Daten und fügen diese in Ihren SOAP-Client und lassen alle Modelle und den zentrallen Controller neu generieren.

Im Regelfall verwenden Sie nur eine sehr kleine Anzahl an SOAP-Calls. Somit ist die Überprüfung der Änderungen schnell erledigt. Normalerweise kommen bei neuen SOAP-Versionen lediglich neue Datenfelder oder neue SOAP-Calls hinzu. Beide Fälle kümmern Sie nicht, wenn Sie mit Datenobjekten arbeiten.

SOAP-Calls im Handbuch

Neue Datenfelder und neue SOAP-Calls finden Sie im Handbuch. Die Liste der einzelnen SOAP-Calls und die Seiten dazu werden automatisch aus dem SOAP-Quelltext generiert. Somit ist gewährleistet, dass keine Datenfelder oder ganze API-Calls im Handbuch fehlen.

Einführung in SOAP

SOAP steht für Simple Object Access Protocol. Es ist letztlich ein Netzwerkprotokoll, das dazu verwendet wird, Daten zwischen zwei Systemen auszutauschen oder auf einem entfernten System eine Aktion auszuführen.

Der eigentliche Datenaustausch findet bei uns über HTTP statt und entspricht somit dem gängigsten Standard. Da SOAP auf XML basiert, entsprechen die eigentlichen Daten einem validen XML-Dokument.

Was ist ein Webservice?

Im Zusammenhang mit SOAP wird häufig von einem Webservice gesprochen. Ein Webservice ist ein allgemeiner Bezeichner für eine Datenschnittstelle. Neben der Technologie SOAP hat sich in den letzten Jahren auch die Technologie REST etabliert. Aufgrund der guten Unterstützung aller gängigen Hochsprachen und der Möglichkeit einer optimalen Validierung haben wir uns für die Technologie SOAP entschieden.

Im Folgenden werden die Begriffe SOAP, SOAP-API, API und Webservice synonym verwendet.

Zielsetzung der plentymarkets SOAP-API

plentymarkets besteht aus vielen tausend Klassen, basiert auf fast 400 Datenbanktabellen und stellt somit eine extreme Menge an Daten und Funktionen zur Verfügung. Die meisten Daten und Funktionen werden über die plentymarkets-Benutzeroberfläche (GUI) dargestellt. Einige Funktionen sind nur für interne Hintergrundprozesse nötig oder werden nur in bestimmten Zusammenhängen verwendet.

Die SOAP-API hat hier die Aufgabe, eine Abstraktionsebe bereitzustellen, die einen wichtigen Teil dieser Funktionen und Daten zugänglich macht.

Die SOAP API ist im Übrigen vorranging dazu da, Daten zwischen zwei Systemen oder Softwareprogrammen über ein fest definiertes Verfahren auszutauschen.

Der von plentymarkets bereitgestellte Webservice ist mittlerweile sehr gut dokumentiert und hat eine enorme Funktionstiefe erreicht.

SOAP-Arbeitsweise

Das Regelwerk der Technologie SOAP ist relativ flexibel gehalten. Dies hat grundsätzlich viele Vorteile, führt aber dazu, dass jede SOAP-API sehr individuell realisiert werden kann. Folglich muss bei der Verwendung jeder SOAP-API mit einem individuellen Aufwand und der Notwendigkeit eines intensiven Studiums der Dokumentation gerechnet werden.

Für einen SOAP-API-Aufruf, hier Call genannt, muss der Sender die eigentlichen Daten in ein XML-Dokument überführen und einige Meta-Daten mitsenden, damit der Empfänger die Daten korrekt verarbeiten kann. Dies kann bei kleinen Datenmengen durchaus dazu führen, dass die Meta-Daten die Byte-Länge der eigentlichen Daten überschreitet.

Weiterhin muss auf Seiten des Clients eine Validierung des XML-Dokuments erfolgen, da nur valide Dokumente vom Empfänger (SOAP-Server) verarbeitet werden können.

Tipp: Automatische Validierung
Sie sollten grundsätzlich eine automatische Validierung implementieren, da bei komplexen SOAP-Calls eine starke Verschachtelung von XML-Strukturen stattfindet und eine manuelle Kontrolle kaum möglich ist.

Aufbau einer SOAP-Nachricht

Eine SOAP-Nachricht besteht im Wesentlichen aus drei Bereichen:

  • Dem Element Envelope, das mit mehreren Attributen versehen werden muss, sowie
  • den Kinder-Elementen Header
  • und Body
Header ist gemäß der Konvention optional, für die plentymarkets SOAP-API allerdings ein zwingend erforderliches Element.

Bild 1: Aufbau einer SOAP-Nachricht

Das Element Envelope enthält Attribute, damit die Nachricht vom Server korrekt verarbeitet werden kann. Weiterhin sind für die Validierung relevante Informationen, wie der Namensraum enthalten. Ein Envelope enthält genau ein Header- und ein Body-Element. Das Header-Element muss dabei immer das erste Element sein.

Der Header beinhaltet den für die Authentifizierung nötigen Schlüssel, den Token. Ohne einen gültigen Token werden SOAP-Nachrichten nicht verarbeitet und die API meldet einen Fehler.

Im Body befinden sich die eigentlichen Daten, die ausgeliefert oder verarbeitet werden müssen.

Beispiel einer SOAP-Nachricht

<SOAP-ENV:Envelope ... xmlns:ns1="http://master.plentymarkets.com/plenty/api/soap/version107/" ...> <SOAP-ENV:Header> <ns2:verifyingToken> <UserID>1</UserID> <Token>85fab9c5b94b7788db0406bd04b2cd6c</Token> </ns2:verifyingToken> </SOAP-ENV:Header> <SOAP-ENV:Body> <ns1:SetOrderStatus> <PlentySoapRequest_SetOrderStatus xsi:type= "ns1:PlentySoapRequest_SetOrderStatus"> <OrderStatus xsi:type="ns1:ArrayOfPlentysoapobject_setorderstatus"> <item xsi:type="ns1:PlentySoapObject_SetOrderStatus"> <OrderID xsi:type="xsd:int">325572</OrderID> <ExternalOrderID xsi:nil="true"/> <OrderStatus xsi:type="xsd:float">3.2</OrderStatus> <Responsible xsi:nil="true"/> </item> </OrderStatus> </PlentySoapRequest_SetOrderStatus> </ns1:SetOrderStatus> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Transport von SOAP-Nachrichten

Für den Transport von SOAP-Nachrichten können grundsätzlich unterschiedliche Möglichkeiten verwendet werden. Bei der plentymarkets SOAP-API kommt jedoch ausschließlich der gängigste Standard zum Einsatz: das Protokoll HTTP

Die beiden wesentlichsten Vorteile von HTTP sind:
  • Jede gängige Hochsprache beherrscht HTTP
  • Der SOAP-Server kann direkt eine Antwort senden, die der Client umgehend verarbeiten kann

Beispiel für einen gültigen HTTP-Header

POST HTTP/1.1 Host: http://master.plentymarkets.com/plenty/api/soap/version107/ Content-Type: text/xml; charset=utf-8 Content-Length: 123 SOAPAction: "SetOrderStatus" <SOAP-ENV:Envelope xmlns:ns1="http://master.plentymarkets.com/plenty/api/soap/...> <SOAP-ENV:Header> <ns2:verifyingToken> <UserID>1</UserID> <Token>85fab9c5b94b7788db0406bd04b2cd6c</Token> </ns2:verifyingToken> </SOAP-ENV:Header> ...

Zwischenstand

Wir haben nun einen kurzen Überblick über den Aufbau einer SOAP-Nachricht erhalten und dabei sicherlich festgestellt, dass es keinem Entwickler zuzumuten ist, SOAP-Nachrichten per Hand zu verfassen.

Weiterhin wird die API laufend weiterentwickelt. Der Aufwand, um einen Call über mehrere Jahre hin aktuell zu halten, ist einfach zu groß.

Es gibt eine Lösung, diesen Prozess zu automatisieren, wie wir im Folgenden sehen werden.

Web Service Description Language

Die Web Service Description Language (WSDL) ist eine Beschreibungssprache auf Basis von XML, mit deren Hilfe die Struktur der einzelnen SOAP-Nachrichten beschrieben wird. Neben der Struktur sind auch alle Parameter und Rückgabewerte enthalten.

Die WSDL-Datei beschreibt exakt alle möglichen SOAP-Nachrichten und kann daher dazu verwendet werden, pro Datentyp ein Datenobjekt zu erzeugen.

Ein API-Aufruf benötigt ein Request-Objekt, das alle relevanten Daten enthält, die vom Server verarbeitet werden sollen. Der Server antwortet immer mit einem Response-Object, das vom Client verarbeitet werden muss.

Der Aufbau aller Objekte wird vollständig durch die WSDL-Datei beschrieben.

Auszug WSDL-Datei

<?xml version="1.0"?> <definitions xmlns:tns="/plenty/api/soap/version107/" ... > <types> <xsd:schema targetNamespace="/plenty/api/soap/.."> <xsd:complexType name="PlentySoapRequest_GetAuthentificationToken"> <xsd:all> <xsd:element name="Username" type="xsd:string" minOccurs="1"/> <xsd:element name="Userpass" type="xsd:string" minOccurs="1"/> </xsd:all> </xsd:complexType> <xsd:complexType name="PlentySoapResponse_GetAuthentificationToken"> <xsd:all> <xsd:element name="Token" type="xsd:string" minOccurs="1"/> <xsd:element name="UserID" type="xsd:int" minOccurs="1"/> <xsd:element name="Success" type="xsd:boolean" minOccurs="1"/> <xsd:element name="ErrorMessages" type="tns:ArrayOfPlentysoapresponsemessage" .../> <xsd:element name="SuccessMessages" type="tns:ArrayOfPlentysoapresponsemessage" .../> </xsd:all> </xsd:complexType> ...

Objekte generieren

Es gibt zwei Möglichkeiten, um alle benötigten Objekte automatisch erstellen zu lassen. In unserem Handbuch stehen neben den hier aufgezeigten Möglichkeiten noch Beispiele für C# und Visual Basic zur Verfügung (siehe die Links unter "Quellcode-Beispiele" in Kapitel 1).

Java

Wenn Sie die Technologie Java einsetzen, können Sie Apache Axis2 verwenden. http://axis.apache.org/axis2/java/core/tools/index.html

Hier steht Ihnen ein Code-Generator per Command-Line oder als Ant-Task zur Verfügung. Weiterhin wird ein Plugin für Eclipse angeboten, um per Wizard Java-Klassen aus einer WSDL-Datei heraus generieren zu lassen.

Hinweise zur Einrichtung von Apache Axis2

http://axis.apache.org/axis2/java/core/tools/eclipse/wsdl2java-plugin.html#Installation

API-Benutzer anlegen

Damit ein Zugriff auf die plentymarkets SOAP-API möglich ist, müssen Benutzer mit speziellen Berechtigungen angelegt werden. Hierfür ist die Klasse API vorgesehen. Ein Benutzer der Klasse API kann Calls ausführen und hat aber sonst keinen Zugriff auf Menüs in Ihrem plentymarkets Backend. Wenn Sie diese Klasse verwenden, müssen Sie sich um Verbindungen zu anderen Menüs keine Gedanken machen. Wir empfehlen daher die Verwendung der Klasse API. Nachdem Sie einen API-Benutzer angelegt haben, aktivieren Sie für diesen Benutzer im Tab Berechtigungen » API einzelne SOAP-Calls.

Pro Anwendung ein API-Benutzer
Ein eigener Benutzer mit speziellen Berechtigungen pro Anwendung empfiehlt sich, um die Zugriffe überwachen zu können. Außerdem empfehlen wir nur die für die Anwendung benötigten Calls zu aktivieren. Spezielle Berechtigungen sind gerade bei der Zusammenarbeit mit externen Dienstleistern sehr wichtig, da bei einem vollständigen Zugriff sensible Daten durch diese entwendet werden können.
API-Benutzer anlegen
  1. Öffnen Sie das Menü Einstellungen » Grundeinstellungen » Benutzer » Konten.
  2. Klicken Sie auf NEU.
    → Ein Bearbeitungsfenster öffnet sich.
  3. Tragen Sie mindestens einen Benutzernamen, den realen Namen sowie ein Passwort (zweimal) ein.
  4. Wählen Sie die Benutzerklasse API.
  5. Klicken Sie auf Speichern, um die Einstellungen zu sichern.
    → Der Benutzer wird angelegt.
  6. Öffnen Sie den soeben angelegten Benutzer.
  7. Öffnen Sie das Tab Berechtigung.
  8. Setzen Sie im Tab API ein Häkchen bei den Calls, auf die der Benutzer Zugriff haben soll.
  9. Klicken Sie auf Speichern, um die Einstellungen zu sichern.
Benutzer anderer Benutzerklassen als API-Benutzer
Andere Benutzerklassen, wie z.B. die Klasse Variabel, sind als API-Benutzer möglich, aber wenn andere Klassen verwendet werden, sind weitere Einstellungen notwendig. Wenn ein Variabler Benutzer einen Call ausführt, muss er auch berechtigt sein, dass Menü im plentymarkets Backend zu sehen auf das sich der Call bezieht, da der Benutzer sonst nicht auf die Daten zugreifen kann.

API-Zugriffe einsehen

SOAP-API-Zugriffe werden im Menü Datenaustausch » API Log aufgeführt. Achten Sie auch auf die Art und Häufigkeit der API-Nutzung, denn es bestehen Limitierungen für Calls. Pro IP beträgt das Limit 150 Calls pro Minute. Im http-Header eines Calls wird angegeben wie viele Calls für diese Minute noch zur Verfügung stehen und wie viele Sekunden die Minute noch hat.
Wenn das Minutenlimit überschritten wurde, wird die IP für 10 Minuten gesperrt. In dieser Zeit können keine weiteren Calls ausgeführt werden. Wenn das Limit überschritten wurde, erhalten Sie außerdem die Meldung HTTP/1.1 429 Too Many Requests. Bei mehr als 80.000 Calls pro Tag behalten wir uns aufgrund der extremen Belastung vor, die aufrufende IP länger zu sperren. Überprüfen und überarbeiten Sie Ihre Implementierungen, wenn die Anzahl Ihrer Calls in diesem Bereich liegt. Eine Überprüfung und Überarbeitung ist bereits ab 40.000 Calls pro Tag ratsam.

API-Zugriffe einsehen:
  1. Öffnen Sie das Menü Datenaustausch » API Log.
  2. Öffnen Sie das Tab SOAP-Log.
  3. Klicken Sie auf Suchen.
    → Die ausgeführten SOAP-Calls werden aufgelistet.

Im Tab SOAP-Statistik des API-Logs wird aufgeführt, wie viele lesende und schreibende Zugriffe pro Tag stattgefunden haben. Die einzelnen Calls werden jedoch nicht aufgeführt.

Ein schlecht entwickelter SOAP-Client kann die Performance Ihres Systems beeinträchtigen.

Negativ-Beispiel - Anbindung eines externen Webshops:

Ein externer Webshop sollte an plentymarkets angebunden werden. Dies ist eigentlich ein Standard-Anwendungsfall, für den die API entwickelt wurde. Bei der Implementierung wurde nicht bedacht, welche Daten in welcher Häufigkeit ausgetauscht werden sollten. Vermutlich aus Angst, eine Information nicht zu erhalten, wurden parallel alle Artikelstammdaten und alle Warenbestände permanent abgefragt und auf den Shop übertragen. Immer wenn ein Prozess fertig war, hat dieser seine Arbeit von vorn begonnen. Am Tag ergab dies über eine Millionen Anfragen, die die Datenbank des Systems langsam machten. Sinnvoll ist hier in einem festen zeitlichen Intervall nur die Daten abzufragen, die sich wirklich in letzter Zeit verändert haben. Für Artikel, Aufträge, Warenbestände etc. gibt es dafür speziell einen Filter.

Authentifizierung

Die Authentifizierung einer SOAP-Nachricht verläuft über den Header, in welchem die Daten UserID und Token übergeben werden müssen.

Der Token ist für 24 Stunden gültig und muss somit nur einmal pro Tag erneuert werden.

Der Token wird ebenfalls über einen speziellen SOAP-Call generiert, wozu der Benutzername und das Passwort benötigt werden.

Weitere Details finden Sie auf der Handbuchseite Authentifizierung.

Meldungen

Die nachfolgende Tabelle listet die Hauptcodes der Erfolgs- bzw. Fehlermeldungen auf. Detailliertere Informationen finden Sie auf den Handbuchseiten der Codes jeweils am Ende der Beschreibung unter Success messages bzw. Error messages.

Code Erläuterung
100 Success
110 Success, but with warnings
200 Success: Added
210 Success: Added, but with warnings
300 Success: Updated
310 Success: Updated, but with warnings
400 Success: Deleted
410 Success: Deleted, but with warnings
800 Error
810 Error: Item limit exceeded
820 Error: Call limit exceeded

Tab. 1: Erläuterungen zu SOAP-Meldungen

Fehlerbehandlung

Grundsätzlich erhalten Sie auf jeden SOAP-Call eine Antwort. Ist dies nicht der Fall, sollten Sie den HTTP-Satuscode auswerten. Es kommt sehr selten vor, aber technische Probleme sind theoretisch immer möglich. Sofern ein großes technisches Problem besteht und dadurch die SOAP-API beeinträchtigt ist, kann es im Einzelfall dazu kommen, dass keine Antwort geliefert wird. In einem solchen Fall erhalten Sie jedoch einen HTTP-Statuscode.

Fehler-Beispiel: 500 Internal Server Error

In über 90% der Fälle kommt ein HTTP 500, weil SOAP-Calls parallel übertragen werden. Dies ist systemseitig ausgeschlossen. Ihr SOAP-Client muss daher dafür sorgen, dass alle Anfragen seriell an den SOAP-Server übertragen werden.

Sie müssen Ihren SOAP-Client zudem so implementieren, dass dieser mit Fehlermeldungen umgehen kann und automatisch entscheidet, ob ein SOAP-Call nochmals übertragen werden muss oder die gesendeten Daten fehlerhaft sind und eine Wiederholung daher nicht sinnvoll ist.

Weitere Details finden Sie auf der Handbuchseite Fehlerbehandlung.

SOAP-Fehlermeldungen

Für jeden SOAP-Call, der vom SOAP-Server verarbeitet wurde, erhalten Sie als Antwort ein entsprechendes Response-Objekt zurück.

Wird beispielsweise eine Liste von 25 neuen Kunden hinzugefügt, gibt es 25 Antwortmeldungen. Sobald ein Kunde korrekt hinzugefügt wurde, wird Success auf true gesetzt und in SuccessMessages ist eine entsprechende Meldung über diesen Kunden enthalten. Werden aus verschiedenen Gründen 10 von den 25 Kunden nicht in das System hinzugefügt, enthält die Antwort 15 SuccessMessages und 10 ErrorMessages. Im Fall der SuccessMessages wird in der Antwort der Code SCU0001 und als Message die neue ID des Kunden zurückgeliefert.

Die einzelnen Fehler-Codes finden Sie im Handbuch auf der Seite des jeweiligen Calls. Die Calls finden Sie unter Call-Index.

Response-Beispiel

<SOAP-ENV:Envelope ...> <SOAP-ENV:Body> <ns1:AddCustomersResponse> <return xsi:type="ns1:PlentySoapResponse_AddCustomers"> <Success xsi:type="xsd:boolean">true</Success> <ErrorMessages xsi:type="ns1:ArrayOfPlentysoapresponsemessage"> <item xsi:type="ns1:PlentySoapResponseMessage"> <Code xsi:type="xsd:string">ECU0022</Code> <Message xsi:type="xsd:string">SOAP_8709</Message> <SubMessages xsi:type=" ns1:ArrayOfPlentysoapresponsesubmessages"/> </item> </ErrorMessages> <SuccessMessages xsi:type="ns1:ArrayOfPlentysoapresponsemessage"> <item xsi:type="ns1:PlentySoapResponseMessage"> <Code xsi:type="xsd:string">SCU0001</Code> <Message xsi:type="xsd:string">2969</Message> <SubMessages xsi:type=" ns1:ArrayOfPlentysoapresponsesubmessages"/> </item> </SuccessMessages> </return> </ns1:AddCustomersResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Aus dieser Rückmeldung ergibt sich, dass einer von zwei Kunden erfolgreich angelegt werden konnte. Warum der zweite Kunde nicht angelegt werden konnte, ergibt sich aus dem Fehlercode.

Mehr zu diesem speziellen Call finden Sie auf der Handbuchseite SOAP-API / Call-Index / AddCustomers

Übersicht der Funktionen und Daten

Zum aktuellen Zeitpunkt stehen Ihnen knapp 140 unterschiedliche SOAP-API-Calls zur Verfügung. Im Handbuch finden Sie auf der Seite Call-Index eine Übersicht mit einem kurzen Erklärungstext, sowie eine Verlinkung auf die jeweiligen Handbuchseiten der Calls.

Grundsätzlich gibt es zwei unterschiedliche Arten von Calls. Neben den klassischen Calls, womit Daten ausgelesen oder verändert werden können, stehen solche zur Verfügung, die statische Informationen liefern.

Solche mit statischen Informationen wurden ganz bewusst so integriert, dass Sie diese Informationen in einer lokalen Datenbank abspeichern können und beispielsweise nur jede Woche oder jeden Monat aktualisieren müssen.

Tipp
Die entsprechenden Calls wurden daher mit einer Limitierung versehen, die in der Übersicht im Call-Index jeweils angegeben ist.

Es ist z.B. nicht sinnvoll, dass Sie vor dem Anlegen eines Auftrags zuerst alle Auftragsstatus-Optionen und alle möglichen Zahlungsarten per SOAP-API laden. Vielmehr handelt es sich hierbei um Informationen, die lokal vorliegen müssen, aber automatisch über eine von Ihnen zu implementierende Logik auf dem aktuellen Stand gehalten werden können.

Grundlagen der SOAP-Client-Entwicklung

Technologie

Verwenden Sie für Ihren SOAP-Client eine Hochsprache, die SOAP optimal unterstützt.

Jede moderne Programmiersprache verfügt über eine eigene SOAP-Library, die die komplette Kommunikation abbildet. Erstellen Sie keine Lösung, die SOAP-Anfragen inklusive dem Versand per HTTP quasi zu Fuß abbildet. Solche Konzepte sind im Regelfall sehr pflegeintensiv und zudem noch extrem anfällig für Fehler.

Framework

Leider begegnen uns immer wieder Fälle, bei denen eine Integration angestrebt wird, ohne ein wirkliches Framework zu planen oder umzusetzen.

Sie werden keine zufriedenstellende Lösung erstellen können, wenn Sie einfach ein oder zwei Skripte erstellen, die Ihnen bestimmte Daten liefern.

Um einen dauerhaft lauffähigen und gut wartbaren SOAP-Client zu entwickeln, brauchen Sie mindestens diese Elemente:

  • Code-Generator
  • Zentraler Controller für die Authentifizierung
  • Zentraler Controller zur Verarbeitung der Ergebnisse und Fehler
  • Controller zur Beschaffung statischer Inhalte
  • Controller zur Speicherung der Ergebnisse oder Zwischenprodukte in einer Datenbank
  • Controller zur Synchronisierung von Daten, die für Abfragen benötigt werden.
  • Mapping-Controller, der die Primärschlüssel der Daten in plentymarkets zu den Primärschlüsseln der Daten der externen Lösung zuordnen kann.
  • Zentraler Logger für Debug-Meldungen
  • Adapter-Architektur, auf der jeder zu verwendende Call aufsetzt.
Fazit:
Ein SOAP-Client ist keine lose Sammlung von ein paar Skripten, sondern eine eigenständige Applikation (Middleware).

Bedarfsanalyse und Planung

Oft wird keine wirkliche Planung und Bedarfsanalyse umgesetzt. Es klingt banal, kommt in der Praxis aber leider regelmäßig vor.

Tipp
Entwickeln Sie nicht einfach drauflos, denn dies führt selten zu einer soliden Software-Architektur!

Befolgen Sie daher diese Punkte:

  • Ermitteln Sie vor dem Entwicklungsstart den genauen Bedarf und dokumentieren Sie die einzelnen Anwendungsfälle.
  • Erstellen Sie einen Plan für Ihr Softwaredesign. Bestenfalls als UML-Diagramm.
  • Entwerfen Sie ein Datenbankmodel zur Speicherung von statischen Informationen und für das Mapping benötigte Daten. Für einige Anwendungsfälle ist es hilfreich, noch mehr Daten vorzuhalten, da für viele schreibende Calls Informationen benötigt werden, die sonst zuerst per SOAP abgefragt werden müssen.
  • Entwerfen Sie einen Plan für die Verteilung des Quellcodes. Es empfiehlt sich der Einsatz einer Versionsverwaltung (SVN oder Git) sowie der Entwurf eines automatischen Checkouts aus dem produktiven System.

Testing

Sie benötigen für das Testing und den eigentlichen Entwicklungsprozess ein Abbild Ihres produktiv laufenden Programms innerhalb einer Entwicklungsumgebung. Da die Entwicklung durch die dauerhafte Wartung nie vollständig endet, sollten Sie sich ein dauerhaft verfügbares plentymarkets-Testsystem erwerben. Dieses ist für knapp 10 EUR pro Monat erhältlich.

Softwareentwicklung ohne eine Testumgebung ist kaum sinnvoll und sicher möglich. Leider wird häufig an produktiv laufenden Systemen gearbeitet. Dies kann schnell extreme Folgen haben:

Beispiel:
Kürzlich hat ein externer Entwickler, der für einen unserer Kunden tätig war, eine vollständige Inventur ausgelöst, da über mehrere Tage tausende fehlerhafte Anfragen übertragen wurden.

Die nötige Inventur war dabei nicht das eigentliche Problem. Viel ärgerlicher war, dass die Warenbewegungen für Kontrollzwecke nicht mehr verwendet werden konnten. Denn im Nachhinein konnten korrekte von fehlerhaften Buchungen nicht mehr unterschieden werden.

Nach oben