Dev-Insider: Web API unterstützt OData v4 ab Smartstore 4.1
Donnerstag, 9. Juli 2020

Dev-Insider: Web API unterstützt OData v4 ab Smartstore 4.1

Das OData v4 v4-Protokoll führt viele Änderungen und neue Funktionen ein, die mehr Flexibilität bei der Modellierung von Diensten und Verbesserungen gegenüber vielen Funktionen der früheren Versionen des Protokolls ermöglichen. Darüber hinaus wurde das OData-Protokoll vor kurzem als OASIS-Standard ratifiziert, was eine noch größere Verbreitung dieses Standards ermöglichen wird.

Smartstore verwendet Microsofts ASP.NET OData Bibliothek, die bereits viele Änderungen und Erweiterungen von OData v4 enthält. Alle OData v3 Endpunkte können auch unter OData v4 unter der gleichen URL erreicht werden.

Eine wichtige neue Funktion ist die Möglichkeit, Funktionen zu definieren, die über GET zugänglich sind. Sie können an Entitäten gebunden oder als ungebundene Servicefunktionen definiert werden. Dies ermöglicht eine bessere Abbildung der Geschäftslogik einer Anwendung über die API. Unter OData v3 konnten solche Endpunkte nur als Aktionen definiert werden, die über POST zugänglich waren.

Die Abfrageoption $expand wurde unter OData v4 erweitert. Optionen wie $select, $filter und $top können nun verwendet werden, um die in der Antwort der Navigationseigenschaften enthaltenen Daten feiner zu steuern. Expands werden nicht mehr über Pfade verschachtelt, sondern über Klammern, z.B. $expand=Customer,BillingAddress($expand=Country) statt $expand=Customer,BillingAddress/Country.

Edm.Float wurde aus den Datentypen entfernt. Zur besseren Unterstützung von Zeitzonen wurde Edm.DateTime durch Edm.DateTimeOffset ersetzt, z.B.  "UpdatedOnUtc": "2020-09-14T16:00:16Z" statt "UpdatedOnUtc": "2020-09-14T16:00:16.5". Edm.Decimal unterstützt keine String-Formatierung mehr, z.B. "Price": 38.2000 statt "Price": "38.2000".

Die API-Rückgabedaten sind unter OData v4 immer JSON-formatiert. Die optionale XML-Formatierung wird derzeit von ASP.NET OData nicht unterstützt. Weitere Informationen zu den Änderungen finden Sie unter den folgenden Links:

https://www.infoq.com/news/2013/05/OData-4/
http://docs.oasis-open.org/odata/new-in-odata/v4.0/cn01/new-in-odata-v4.0-cn01.html

Die interaktive Dokumentation mit Swagger ist eine wichtige Hilfe. Mit einem Try-it-out-Button unter ~/swagger/ui/index können Testanfragen direkt an die API gesendet werden. Die Smartstore Web API unterstützt Swagger über eine ältere Komponente namens Swashbuckle. Diese Dokumentation ist derzeit unvollständig. Es ist geplant, sie nach der Migration auf ASP.NET Core zu aktualisieren und zu vervollständigen.

Das Metadaten-Dokument, das unter ~/odata/v1/$metadata verfügbar ist, beschreibt das Entity Data Model (EDM) des OData-Dienstes. Das XML-formatierte Metadaten-Dokument zeigt die vollständige Datenstruktur des OData-Dienstes und kann zur Generierung von Client-Code verwendet werden.

Der Quellcode der Smartstore Web API ist offen und kann hier eingesehen werden. Außerdem sind zwei Client-Tools zum Testen der API verfügbar: eine Windows Forms-Anwendung und ein reiner JavaScript-Client.

Ihr Kommentar