Einen API-Client erstellen

Diese Dokumentation gibt Ihnen einen Überblick darüber, wie Sie einen API-Client, auch API-Consumer genannt, erstellen. Sie können Ihren Consumer in jeder gängigen Programmiersprache entwickeln. Da OData ein standardisiertes Protokoll ist, stehen für verschiedene Plattformen zahlreiche Frameworks und Toolkits zur Verfügung.

Die ASP.NET Web API ist ein Framework zur Erstellung von Web-APIs auf Basis des .NET Frameworks. Sie verwendet HTTP als Anwendungsprotokoll (und nicht als Transportprotokoll), um Daten basierend auf den Anfragen des Clients zurückzugeben. Die Web API kann die Daten entsprechend dem in der Anfrage angegebenen Medientyp zurückgeben. Standardmäßig werden JSON-basierte Antworten bereitgestellt.

Das Open Data Protocol (OData) ist ein standardisiertes Webprotokoll, das eine einheitliche Möglichkeit bietet, Daten mithilfe von REST-Praktiken bereitzustellen, zu strukturieren, abzufragen und zu bearbeiten. OData bietet außerdem eine einheitliche Möglichkeit, Metadaten über die Daten darzustellen. Dadurch können Clients mehr über das Typsystem, die Beziehungen und die Struktur der Daten erfahren.

Voraussetzungen

Die Smartstore Web API erfordert eine Konfiguration durch den Shopbetreiber, bevor sie verwendet werden kann. Zunächst muss der Shopbetreiber das Web-API-Plugin im Smartstore-Backend installieren. Die Plugin-Technologie ermöglicht es ihm, die gesamte Web API jederzeit zu aktivieren oder zu deaktivieren, ohne den Onlineshop zu beeinträchtigen.

Im nächsten Schritt wird die API auf der Konfigurationsseite des Plugins eingerichtet. Dabei geht es vor allem darum, einzelnen Mitgliedern Zugriff auf die API und die Daten des Onlineshops zu gewähren. Dazu kann der Shopbetreiber für jedes registrierte Mitglied einen öffentlichen und einen geheimen Schlüssel erstellen.

Nur ein registriertes Mitglied, das über beide Schlüssel verfügt, hat Zugriff auf die API. Um einem Mitglied den Zugriff auf die API zu entziehen, kann der Shopbetreiber entweder die Schlüssel des Mitglieds löschen (dauerhafter Ausschluss) oder deaktivieren (vorübergehender Ausschluss). Die Rollen und Berechtigungen eines Mitglieds werden beim Zugriff auf Daten über die API berücksichtigt.

Authentifizierung

Die Smartstore Web API verwendet die Methode Basic Authentication über HTTPS, um Daten mithilfe öffentlicher und geheimer Schlüssel vor unbefugtem Zugriff zu schützen.

OData – ein offener Standard für den Datenzugriff

Durch die Bereitstellung von Smartstore-Funktionen als REST-basierte OData-Dienste ermöglichen Smartstore-Anwendungen den Austausch von Daten mit einer Vielzahl von Geräten, Technologien und Plattformen auf eine leicht verständliche und einfach nutzbare Weise.

OData – Häufig gestellte Fragen

Warum sollten Entwickler von REST APIs OData verwenden? Wer setzt OData ein? In diesen kurzen FAQs erfahren Sie mehr über Funktionen von OData wie FHIR, RFC, IETF, Sicherheit, JSON, Batch-Anfragen und Paginierung.

Das exponentielle Wachstum von SaaS-Anwendungen hat zu einer starken Zunahme von REST APIs geführt. Heute sind Tausende von APIs im Programmable Web registriert, und Untersuchungen zeigen, dass jede Woche rund 40 neue APIs hinzukommen. Das bedeutet, dass Entwickler heute einen Großteil ihrer Zeit damit verbringen, neue APIs zu erlernen, anstatt die eigentliche Anwendung zu entwickeln. Um dieses Problem zu lösen, hat Microsoft den OData-Standard für die Erstellung von REST APIs entwickelt.

OData definiert eine Reihe von Best Practices für die Entwicklung und Nutzung von RESTful APIs. OData hilft Ihnen, sich auf Ihre Geschäftslogik zu konzentrieren, ohne sich beim Erstellen von RESTful APIs um die unterschiedlichen Ansätze für die Definition von Request- und Response-Headern, Statuscodes, HTTP-Methoden, URL-Konventionen, Medientypen, Payload-Formaten, Abfrageoptionen usw. kümmern zu müssen.

1. Warum sollte ich OData verwenden?

Mit der zunehmenden Anzahl von APIs stellt jede Organisation eigene REST-, SOAP- oder Bulk-APIs für den Zugriff auf ihre Daten bereit. Einige entwickeln zusätzlich eigene Abfragesprachen wie ROQL (Oracle Service Cloud) oder SOQL (Salesforce). Dadurch wird es für Unternehmen und ihre Entwicklungsteams schwierig, mit all diesen unterschiedlichen APIs zu arbeiten.

Hier bietet OData einen entscheidenden Vorteil. OData verfolgt einen standardisierten Ansatz zur Implementierung von REST APIs und ermöglicht SQL-ähnliche Abfragen über diese RESTful APIs. OData ist im Wesentlichen SQL für das Web, aufgebaut auf Standardprotokollen wie HTTP, JSON und ATOM und unter Nutzung des REST-Architekturstils. Anhand von Codebeispielen erfahren Sie in diesem Tutorial-Blog, wie OData die Arbeit mit APIs vereinfachen kann: Marketo REST API vs. Eloqua REST API vs. OData.

2. Welche Unternehmen setzen OData ein?

Einige Entwickler fragten sich, ob Microsoft das einzige Unternehmen ist, das OData vorantreibt. Sie waren jedoch überrascht festzustellen, dass OData von zahlreichen Technologien und Unternehmen eingesetzt wird, darunter SAP, IBM, Salesforce, Tableau, Databoom, Progress, Red Hat und Dell. Das OData-Ökosystem umfasst eine Liste von Nutzern und Anbietern, die wir verfolgen. Diese Liste wächst jedoch schneller, als wir sie vollständig erfassen können.

3. Wie steht FHIR mit OData in Verbindung?

FHIR (Fast Healthcare Interoperability Resources Specification) ist ein Standard für den elektronischen Austausch von Gesundheitsinformationen. Um eine echte Interoperabilität von FHIR zu gewährleisten, wird empfohlen, dass Systeme die in der OData-Spezifikation festgelegten Regeln für den Parameter $search verwenden. Darüber hinaus nutzt FHIR OAuth, um eine vertrauenswürdige Beziehung zum Client herzustellen und eine zusätzliche Sicherheitsebene zu schaffen.

4. Entspricht OData den Internetstandards?

Ja. OData wird unter dem OASIS OData Technical Committee (TC) standardisiert, wodurch seine Entwicklung und Pflege als herstellerneutraler Standard sichergestellt wird. OData basiert außerdem auf zahlreichen RFC-Standards der IETF (Internet Engineering Task Force). Dazu gehören unter anderem folgende RFC-Standards:

  • RFC7240, RFC7230, RFC7231, RFC7232, RFC7235 – HTTP-1.1-Spezifikationen (Hinweis: RFC2616 und RFC2617 wurden durch diese neueren Spezifikationen ersetzt)
  • RFC5023 – Atom Publishing Protocol
  • RFC2119 – Schlüsselwörter zur Angabe von Anforderungsstufen in RFCs
  • RFC5789 – Patch-Methode für HTTP
  • RFC3629 – UTF-8
  • RFC7159 – JSON (Hinweis: RFC4627 wurde durch diese Spezifikation ersetzt)
  • RFC3986 – URI
  • RFC2046 – Multipurpose Internet Mail Extensions (MIME)

5. Ist OData anfällig für SQL-Injection oder andere Sicherheitsangriffe?

OData ist eine Abfragesprache ähnlich wie SQL, mit der alle Daten abgefragt werden können, die vom Modell bereitgestellt werden. Wie bei SQL muss die Anwendung entsprechende Einschränkungen vorsehen, wenn nur bestimmte Teile des Modells bereitgestellt werden sollen.

Was Sicherheitsangriffe betrifft, hängt dies von der jeweiligen Implementierung ab. Es sind keine Sicherheitslücken bekannt, die spezifisch die OData-Spezifikation betreffen. Da OData als REST API bereitgestellt wird, muss die jeweilige Implementierung wie jede andere REST API gegen Sicherheitslücken geschützt werden.

6. Wie kann ich die JSON-Version entsprechend dem Schema verwalten?

Das JSON, das von einer Abfrage zurückgegeben wird, wird durch das Modell definiert. Wenn sich das Modell ändert, ändert sich auch das JSON in der Antwort. In der OData-4.0-Spezifikation bietet die CSDL-Syntax, mit der das OData-Modell definiert wird, keine Möglichkeit, einem Modell eine Version zuzuweisen. Die ursprüngliche Absicht war, dass sich das Modell einer einmal veröffentlichten OData-API unter einer bestimmten URL nicht mehr ändert. Bei einer Änderung des Modells sollte eine neue, gegebenenfalls versionierte URL bereitgestellt werden.

Aufgrund zahlreicher Anfragen nach einer Möglichkeit zur Versionierung des Modells wurde in der kommenden OData-4.0.1-Spezifikation eine Schema-Version-Annotation in CSDL ergänzt. Für OData 4.0.1 kann eine bestimmte Version des Modells über den Request-Header Schema Version angefordert werden.

7. Unterstützt OData Batch-Anfragen wie bei E-Mails?

OData unterstützt Batch-Anfragen. Batch-Anfragen ermöglichen es, mehrere Operationen in einer einzigen HTTP-Anfrage zusammenzufassen. Eine Batch-Anfrage wird als Multipart-MIME-1.0-Nachricht gemäß RFC 2046 dargestellt. Dabei handelt es sich um ein Standardformat, das die Darstellung mehrerer Teile innerhalb einer einzigen Anfrage ermöglicht, wobei jeder Teil einen unterschiedlichen Content-Type haben kann (wie in [OData-Atom] und [OData-JSON] beschrieben).

Batch-Anfragen werden als einzelne HTTP-POST-Anfrage an den Batch-Endpunkt eines Dienstes gesendet, der sich unter der URL $batch relativ zur Service-Root befindet. Die Batch-Anfrage MUSS einen Content-Type-Header enthalten, der einen Content-Type von multipart/mixed sowie eine Boundary-Spezifikation gemäß RFC 2046 angibt.

8. Wie sieht es mit der Paginierung aus? Funktioniert die Paginierung auch bei häufig wechselnden Inhalten wie bei Twitter?

OData wurde als eine Reihe von Konventionen entwickelt, die auf bestehenden Standards aufbauen und gemeinsame Darstellungen für gängige Funktionen bereitstellen. Um die Interoperabilität zwischen Client und Server zu unterstützen, definiert diese Spezifikation mehrere Konformitätsstufen für einen OData-Dienst sowie Mindestanforderungen an einen OData-Client, um die Interoperabilität zwischen verschiedenen OData-Diensten zu gewährleisten.

Für die minimale Konformitätsstufe muss OData serverseitiges Paging unterstützen. Darüber hinaus kann auch clientseitiges Paging über Abfrageoptionen wie die folgenden verwendet werden:

  • orderby
  • select
  • skip
  • top
  • filter
  • expand

Diese Paginierung erfolgt pro Abfrage. Wenn Abfragen beispielsweise für einen Streaming-Dienst wie Twitter verwendet werden, erfolgt die Abfrage für einen bestimmten Zeitraum. Wenn innerhalb dieses Zeitraums mehr Daten vorhanden sind, werden die Daten auf mehrere Seiten aufgeteilt.

9. Unterstützt OData Prozeduren? Können JOINs über föderierte Datenbanken hinweg ausgeführt werden?

Ja, OData unterstützt Prozeduren. In RESTful APIs kann es benutzerdefinierte Operationen geben, die komplexe Logik enthalten und häufig verwendet werden. Zu diesem Zweck unterstützt OData die Definition von Funktionen und Aktionen zur Darstellung solcher Operationen. Diese sind ebenfalls Ressourcen und können an bestehende Ressourcen gebunden werden. Darüber hinaus schließt OData die Zusammenführung von Daten aus mehreren Quellen nicht aus.

Einschränkungen

Die Web API wird hauptsächlich zum Austausch von Rohdaten verwendet. Mit wenigen Ausnahmen sind weitere Servicefunktionen von Smartstore über die API nicht zugänglich. Wenn unterschiedliche Daten in großem Umfang ausgetauscht werden sollen, kann ein separates Plugin die flexiblere Lösung sein. Ein solches Plugin fungiert als Middleware zwischen Smartstore und Ihrer Anwendung und kann grundsätzlich auf alle Servicefunktionen von Smartstore zugreifen.

Die Entscheidung, ob Daten mit Smartstore über die Web API oder über ein benutzerdefiniertes Plugin ausgetauscht werden sollen, ist ein wichtiger Schritt und sollte sorgfältig abgewogen werden. Häufig stoßen Entwickler beim Datenaustausch mit der Web API an Grenzen, weil die falsche Lösung gewählt wurde.

Dokumentation & Ressourcen

Haben Sie Fragen zu diesem Thema? Oder möchten Sie uns Ihr Feedback senden? Dann erreichen Sie uns über das Kontaktformular, per E-Mail an info@smartstore.com oder telefonisch von Montag bis Freitag zwischen 10 und 16 Uhr unter der Nummer +4923153350.