OData Connector
Content
Introduction
The OData connector allows to read and write data from servers that provides an OData RESTful service v2. For example it gives you the possibility to access data of a SAP system if your SAP Gateway provides an OData service.
When you trigger the crawling process it creates an ApiOmat module with classes and properties according to the provided OData metadata entities and properties.
After crawling has finished you're able to access the data from a frontend in the known ApiOmat way.
Key Capabilities
|
Capability |
Description |
|
Converting OData entities to ApiOmat classes |
With the crawling process you're able to create ApiOmat classes and properties from metadata which are provided by the odata service |
|
Reading data |
Reading data from odata collections |
|
Querying data |
Sending Odata filter queries to retrieving filtered data from service (see OData filter query section below) |
|
Reading references |
Getting data of navigation properties |
|
Saving/Update data |
Add a new entry to a collection or update existing one |
Module Setup & Configuration
|
Parameter-Name |
Default Value |
Explanation |
|
Thread-pool-size |
0 |
Number of threads used to create the Metamodels and Attributes. Should be set to 0 to trigger an automatic computation of values. Change only if you encounter any problems with the computed values |
|
enable logging |
false |
If set to true detailed logging will be enabled |
Crawling
Crawling is the essential part of this connector. It converts the OData metadata to a new ApiOmat module with classes and properties. If you start crawling a new module will be created prefixed with given module name.
The crawling process can be started via dashboard or REST call. Find below the explanation of config parameters:
|
Parameter-Name |
Required |
Example |
Explanation |
|
Base URL |
|
URL to the OData RESTful v2 service |
|
|
apiOmat module name |
|
CrawlProducts |
Prefix for new (or updated) module. Module name will consisting of <prefix>+<app backend name> |
|
apiOmat Customer name |
|
mustermann |
Name of the customer which owns the app backend |
|
addtional http headers send to odata interface |
|
SSL_CLIENT_CERT|SSL_CLIENT_VERIFY |
list of header names seperated by | whose values given from client will be forwarded to OData service |
|
TRUE to overwrite previous crawling |
|
TRUE |
If set to TRUE then existing module with same name will be overwritten |
|
App name |
|
ODataSampleApp |
Name of the app backend where new module will be created for |
Dashboard
After adding OData Connector from marketplace to your app backend you must navigate to My Modules > Native Modules and go to the section labeled ODataConnector. There you have to fill-in the config parameters and click on button "Triggers a new crawling process"
After refreshing your module list (go to Module Market > Refresh) the crawled module should be visible within your app backend's navigation bar. To create and read the data of the crawled module use the data editor in your Dashboard.
The guide Data give some detail on how to create and read data object instances.
REST Call
Crawling OData entities may also be triggered via REST by calling the following endpoint (see API docs for more information):
curl -X GET --header 'Accept: text/plain' --header 'X-apiomat-system: LIVE' --header 'If-None-Match: false' --header 'X-apiomat-apikey: 887157215189025405' -u demoUser:password 'http://localhost:8080/yambas/rest/modules/odataconnector/DemoBackend/spec/crawler?url=http%3A%2F%2Fservices.odata.org%2FV2%2FOData%2FOData.svc&moduleName=RestCrawlProducts&customerName=demoUser&reCrawl=true'A successfully crawled module can then be querried by the module REST endpoint:
curl -X GET --header 'Accept: application/json' --header 'X-apiomat-system: LIVE' --header 'If-None-Match: false' --header 'X-apiomat-apikey: 887157215189025405' -u demoUser:password 'http://localhost:8080/yambas/rest/modules/RestcrawlproductsDemoBackend'For more details about creating and reading data object instances just visit the section Using the REST interface.
OData Service Authentication
Sometimes you need to authenticate against an OData Service. The OData user and password that is needed to crawl OData entities have to be applied to the base url. Those information are placed in front of the domain name of the OData base url, e.g.:
http://odataTommy:myPass@services.odata.org/V2/OData/OData.svcThe OData Connector module internally extracts username and password and sets them as connection credentials to the OData crawling request.
These credentials must be from a technical user (instead of a session user). They get saved in the ApiOmat database in an object of a meta data class in the app's scope instead of as module configuration, because module configuration is valid across apps, but the credentials should only be visible for the app for which the service was crawled.
OData Filter Query
One of OData's feature is to filter your responses by query. Normally you would do this by appending $filter=<values> (see Odata filter queries).
The ODataConnector module contains an own REST parameter to define a specific query. This query parameter will be delegated to the OData Service as odata filter.
Example:
The ApiOmat GET REST call to the end point ...
<Apiomat_Yambas_BASE_URL>/apps/<appName>/models/<crawledModuleName>/Cars?q=Price+lt+200000... will be internally transferred to the OData service call ...
<ODataService_BASE_URL>/Cars/?$filter=Price+lt+200000
Dashboard Example:
Via Dashboard you can define your OData filter query within the provided query input field:
OData Composite Primary Keys
OData supports objects with multiple primary keys. To query those objects via OData REST call you need to append all keys to the REST end point, e.g. https://host/service/Orders(1)/Items(OrderID=1,ItemNo=2) .
During the OData service crawling those object will be converted to ApiOmat objects with combined foreignId. The combined foreignId looks like the following:
<firstPrimaryKey>__<secondPrimaryKey>e.g.:1__21__2__3 
The order of combined foreignId elements is important. Currently it has to be the same order like the defined ODataService primary key compound.
Limitations
At the moment:
-
data cannot be updated (doPut)
-
data cannot be deleted (doDelete)
-
referenced data cannot be removed (doDeleteRef)
-
referenced data cannot be added (doPostRef)
Furthermore a new data instance can only be created if all OData properties of the entity are present.