The OData v4 protocol introduces a lot of changes and new features that allow more flexibility in the way to model services and improvements over many features from the past versions of the protocol. In addition to this, the OData protocol has been recently ratified as an OASIS standard which will allow an even wider distribution of this standard.
Smartstore uses Microsoft's ASP.NET OData library which already includes many changes and enhancements of OData v4. All OData v3 endpoints can also be accessed under OData v4 using the same URL.
An important new feature is the ability to define functions accessible via GET. They can be bound to entities or defined as unbound service functions. This allows a better mapping of the business logic of an application via the API. Under OData v3, such endpoints could only be defined as actions accessible via POST.
The $expand query option has been extended under OData v4. Options such as $select, $filter and $top can now be used to control the data contained in the response of Navigation Properties more finely. Expands are no longer nested using paths, but by using parenthesis, e.g. $expand=Customer,BillingAddress($expand=Country) instead of $expand=Customer,BillingAddress/Country.
Edm.Float has been removed from the data types. To better support time zones Edm.DateTime has been replaced by Edm.DateTimeOffset, e.g. "UpdatedOnUtc": "2020-09-14T16:00:16Z" instead of "UpdatedOnUtc": "2020-09-14T16:00:16.5". Edm.Decimal doesn't support string formatting anymore, e.g. "Price": 38.2000 instead of "Price": "38.2000".
The API return data is always JSON formatted under OData v4. Optional XML formatting is currently not supported by ASP.NET OData. More about the changes can be found under the following 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
Interactive documentation using Swagger is an important help. With a try-it-out button under ~/swagger/ui/index test requests can be sent directly to the API. The Smartstore Web API supports Swagger via an older component called Swashbuckle. This documentation is currently incomplete. It is planned to update and complete it after the migration to ASP.NET Core.
The metadata document available at ~/odata/v1/$metadata describes the Entity Data Model (EDM) of the OData service. The XML formatted metadata document shows the complete data structure of the OData service and can be used to generate client code.
The source code of the Smartstore Web API is open and can be accessed here. Furthermore, two client tools are available for testing the API: a Windows Forms application and a pure JavaScript client.