This documentation gives you an overview of how to build an API client, also known as API consumer. It uses C# code, but you can build your consumer in any common programming language. As OData is a standardized protocol, there are a lot of frameworks and toolkits available for various platforms.
The ASP.NET Web API is a framework for building web APIs on top of the .NET framework. It uses HTTP as an application protocol (rather than a transport protocol) to return data based on the client requests. The Web API is able to return the data appropriately based on the media type specified by the request. By default, it provides JSON and XML based responses.
The Open Data Protocol (OData) is a standardized web protocol that provides an uniform way to expose, structure, query and manipulate data using REST practices. OData also provides a uniform way to represent metadata about the data, allowing clients to know more about the type system, relationships and structure of the data.
Prerequisites
The Smartstore Web API requires configuration by the storekeeper in order to start working. First of all, the storekeeper must install the Web API plugin in the backend of Smartstore. The plugin technology gives him the opportunity to activate or deactivate the entire Web API at any time without any impact on the online store.
The next step is to configure the API on the plugin's configuration page. The main thing here is to provide individual members access to the API and the data of the online store. Therefore, the storekeeper can create a public and a secret key for each registered member. Only a registered member with both keys has access to the API. To exclude a member from the API, the storekeeper can either delete the keys of the member (permanent exclusion) or disable them (temporary exclusion). A member's roles and rights are taken into consideration when data is accessed via the API.
The consumer must transmit the public key through a custom HTTP header field, which identifies the member accessing the API. The secret key, on the other hand, should never ever be sent over the wire! It should only be known by the storekeeper and the member accessing the Web API. It is used solely for encryption, as described in the following chapters.
OData - an Open Standard for Data Access
Smartstore and OData
By exposing Smartstore functionality as REST-based OData (Open Data Protocol) services, Smartstore applications to share data with a wide range of devices, technologies, and platforms in a way that is easy to understand and consume.
OData FAQs: Why Should REST API Developers Use OData?
Why use OData? Who is adopting OData? In this quick FAQ, learn about features of OData like FHIR, RFC, IETF, Security, JSON, batch requests and pagination.
The exponential growth of SaaS applications has led to an explosion of REST APIs. As of today, there are almost 18,000 APIs registered on the Programmable Web, and research shows that around 40 new APIs are being added every week. This means that a developer today will be spending most of his or her time learning new APIs instead of building the application itself. To solve this problem, Microsoft founded the OData standard for building REST APIs.
OData (Open Data Protocol) defines a set of best practices for building and consuming RESTful APIs. OData helps you focus on your business logic while building RESTful APIs without having to worry about the various approaches to define request and response headers, status codes, HTTP methods, URL conventions, media types, payload formats, query options, etc. We are proud to serve on the OData Technical Committee (in fact, we were the first member of this committee) along with other technical giants such as CA and Citrix.
1. Why should I use OData?
As APIs continue to explode, each organization exposes its own unique REST/SOAP/Bulk APIs for consuming their data. And some of them also come up with their own unique query language such as ROQL (Oracle Service Cloud), SOQL (Salesforce), etc. This makes it difficult for an enterprise and its development team to be able to learn and code against all these different APIs.
This is where OData is very useful. OData advocates a standard way of implementing REST APIs that allows for SQL-like querying capabilities using these RESTful APIs. OData is essentially SQL for the web built on top of standard protocols – HTTP, JSON & ATOM – while leveraging the REST architecture style. Learn through code samples how OData can simplify your life in this tutorial blog: Marketo REST API vs Eloqua REST API vs OData.
2. Which companies are adopting OData?
Some of the developers were curious to know whether Microsoft was the only company pushing OData. However, they were surprised to realize that OData has been adopted by a lot of technologies and companies including SAP, IBM, Salesforce, Tableau, Databoom, Progress, Red Hat and Dell. The OData ecosystem has a list of some of its consumers and producers and the slide below is a list we’re tracking, but it’s growing faster than we can keep up with.
3. How is FHIR related to OData?
FHIR, or Fast Healthcare Interoperability Resources Specification, is a standard for exchanging healthcare information electronically. In order to make FHIR truly interoperable, it is recommended that systems use the rules specified by OData specification for the $search parameter. Further, FHIR also uses OAuth in order to establish a trusted relationship with the client for an extra layer of security.
4. Is OData compliant with the Internet Standards?
Yes, OData is an OASIS standard and has been recently ratified as an ISO standard. It is also based on a lot of the RFC standards from the IETF (Internet Engineering Task Force). Here are some of the RFC standards it uses:
RFC7240, RFC7230, RFC7231, RFC7232, RFC7235 - HTTP 1.1 Specifications (Note: RFC2616, RFC2617 have been obsoleted and replaced by these latest specifications)
RFC5023 The Atom Publishing Protocol
RFC2119 Keywords for use in RFCs to Indicate Requirement Levels
RFC5789 Patch Method for HTTP
RFC3629 UTF-8
RFC7159 JSON (Note: RFC4627 has been obsoleted and replaced by this specification)
RFC 3986 URI
RFC 2046 Multipurpose Internet Mail Extensions (MIME)
5. Is OData susceptible to SQL Injection or other security attacks?
OData is a query language like SQL with which you can query anything that is exposed by the model. Like SQL, if the application only wants to expose certain parts of the model, the application will need to provide those restrictions.
As for security attacks, this will depend on the implementation. They are not aware of any security flaws that are specific to the OData specification. Since OData is exposed as a REST API, the implementation must guard against security vulnerabilities like any other REST API.
From a Progress DataDirect product perspective, our hybrid connectivity services follow the OWASP guidelines for protecting against known security vulnerabilities. DataDirect Cloud is also subject to routine security scans and penetration testing both by internal resources and independent external resources.
6. How can I manage the JSON version according to the schema?
The JSON that is returned from a query is defined by the model. If the model changes, the JSON in the response will change. In the OData 4.0 spec the CSDL syntax that is used to define the OData model does not have a way to assign a version to a model. The intent was that once an OData API was published at a given URL, its model would not change. If there was a change to the model, then a new (possibly versioned) URL would be provided.
However, there were enough requests for versioning the model that a Schema Version annotation was added to the CSDL in the coming OData 4.0.1 specification. A specific version of the model can be requested with the Schema Version request header for OData 4.0.1
7. Can OData support batch requests like in an email? (Work in progress)
OData supports batch requests. Batch requests allow grouping multiple operations into a single HTTP request payload. A batch request is represented as a Multipart MIME v1.0 message RFC 2046, a standard format allowing the representation of multiple parts, each of which may have a different content type (as described in [OData-Atom] and [OData-JSON]), within a single request.
Batch requests are submitted as a single HTTP POST request to the batch endpoint of a service, located at the URL $batch relative to the service root. The batch request MUST contain a Content-Type header specifying a content type of multipart/mixed and a boundary specification as defined in RFC 2046.
8. What about pagination? Does pagination work for frequently changing content like Twitter?
OData is designed as a set of conventions that can be layered on top of existing standards to provide common representations for common functionality. To aid in client/server interoperability, this specification defines multiple levels of conformance for an OData Service, as well as the minimal requirements for an OData Client to be interoperable across OData services. For a minimum conformance, OData must support server-driven paging. Beyond that one could also apply client-side paging through query options such as Orderby, select, skip, top, filter, expand and inlinecount.
This pagination is done on a per query basis. Typically if query capability is done on a streaming service like Twitter, then the query is done for a particular time slice. If there is more data in that time slice, then the data will be broken up into pages.
9. Does OData support procedures? Can we perform JOINs across Federated databases?
Yes, OData supports procedures. In RESTful APIs, there can be some custom operations that contain complicated logic and can be frequently used. For that purpose, OData supports defining functions and actions to represent such operations. They are also resources themselves and can be bound to existing resources. Further, OData does not preclude federating data from multiple sources.
Limitation
The Web API is primarily used to exchange raw data. With a few exceptions, further service functions of Smartstore are not accessible via
the API. If different data is to be exchanged on a large scale, the more flexible solution may be to use a separate plugin. Such a plugin
acts as middleware between Smartstore and your application and can in principle access all service functions of Smartstore.
Doku
http://docs.smartstore.com/display/SMNET32/Web+API
http://documents.smartstore.com/SmartStoreNET_Web_API_v30.pdf