This section is focused on explaining principles of using General BECS OData Service and its sample usage in BECS integration project, describing it in two major subsections:​​​​​​​

OData (Open Data Protocol) is an OASIS standard that defines the best practice for building and consuming RESTful APIs. OData helps you focus on your business logic while building RESTful APIs without having to worry about the approaches to define request and response headers, status codes, HTTP methods, URL conventions, media types, payload formats and query options etc. OData also guides you about tracking changes, defining functions/actions for reusable procedures and sending asynchronous/batch requests etc. Additionally, OData provides facility for extension to fulfil any custom needs of your RESTful APIs.

OData RESTful APIs are easy to consume. The OData metadata, a machine-readable description of the data model of the APIs, enables the creation of powerful generic client proxies and tools. Some of them can help you interact with OData even without knowing anything about the protocol.

BECS is open and very powerful platform used in wide range of industrial areas and business scenarios. To increase possibility of using BECS we hardly working also on adaptation of different standards for communication and keep the flexibility and power of BECS integration Visual Modeling unchanged.

General BECS OData Service layer was designed as another general way how to start integration via REST API call for any integration project (after adaptation of standard REST, SOAP and graphQL).

BECS OData Service is the layer for using OData queries to retrieve BECS enabled/integrated data from any BECS integration solution.

Please do not forget, that BECS is driven by integration visual projects (called BECS Integration Project or BECS IP). The major reason of adapting OData Service layer is to enable using of any standard BECS IP also via OData channel (request/response).

This will allow to integrate with any OData compliant system easily and use full power of BECS projects and connectors as well.

In following picture, you can see the global architecture of BECS OData Service and its cooperation with standard BECS IP. Schema shows standard flow for OData requestor:

 

1.2.3.1.2 ​​​​​​​Directive “?format”

If required to switch payload to json format, use directive “?format=json”:

Request:

https://uks-qa-becs.bentley.com/BECS.Odata.Translator/api/odata/Customers?format=json

Response:

 

1.2.3.2 Metadata retrieve

 

1.2.3.3 Basic metadata

As standard in OData syntax by placing only endpoint URL, the basic metadata definition will be returned:

Request:

https://uks-qa-becs.bentley.com/BECS.Odata.Translator/api/odata/

Response:

 

1.2.3.4 Advanced metadata – “directive $metadata”

To get advance information about connected objects, BECS OData Server supports $metadata directive. In this advanced view is possible to see all details about attributes as well as keys definitions:

Request:

https://uks-qa-becs.bentley.com/BECS.Odata.Translator/api/odata/$metadata

Response:

​​​​​​​

1.2.3.5 Data retrieve

1.2.3.5.1 Simple Data Request

As defined in OData standards also BECS OData Service returned data via simple query request – just place name of the data object after root endpoint URL (data object listed from basic metadata request):

Please be aware, that Service EndPoint depends on machine where the service is installed, so it needs to be changed to proper architecture every time!

Request:

https://uks-qa-becs.bentley.com/BECS.Odata.Translator/api/odata/Customers

Response:

 

1.2.3.6 ​​​​​​​Field selection, directive “?select”

For retrieving only selected fields can be used “?select” directive.

Request:

https://uks-qa-becs.bentley.com/BECS.Odata.Translator/api/odata/Customers?&select=ContactTitle,ContactName

Response:

 

1.2.3.6.1 ​​​​​​​Data filtering Request

As defined in OData standards also BECS OData Service supports two ways of filtering:

 

​​​​​​​1.2.3.6.1.1 Using native filtering condition

By placing filtering condition in brackets after the data object name, BECS OData Service will return filtered data. In this syntax only Key Filed attributes can be used!

Request:

https://uks-qa-becs.bentley.com/BECS.Odata.Translator/api/odata/Customers(CustomerID='ANATR')

Response:

​​​​​​​

1.2.3.6.1.2 Using filtering by directive “$filter”

By directive $format can be defined sophisticated filtering

Request:

https://uks-qa-becs.bentley.com/BECS.Odata.Translator/api/odata/Customers?filter=CompanyName%20eq%20%27Alfreds%20Futterkiste%27

*in URL query above is formatted “ “ (space) as “%20” (standard web formatting)

Response:

 

​​​​​​​1.2.3.6.2 Data linking Request

As defined in OData standards also BECS OData Service supports easy linkage of data objects:

For example showing also all sales orders for selected customer (ANATR) use following query:

Request:

https://uks-qa-becs.bentley.com/BECS.Odata.Translator/api/odata/Customers(CustomerID='ANATR')/Orders

Response:

​​​​​​​

1.2.3.6.3 Data Paging

To support records sub-selection of payload can be used following directives:

 

1.2.3.6.3.1 ​​​​​​​Directive ?Top

For returning only TOP x records is possible to use directive “?top” – for example return of top 3 Customers:

Request:

https://uks-qa-becs.bentley.com/BECS.Odata.Translator/api/odata/Customers?top=3

Response:

 

1.2.3.6.3.2 Directive &skip

For starting from defined record is possible to use directive “&skip” – for example return of top 3 Customers, but skip the first one (=start from second):

Request:

https://uks-qa-becs.bentley.com/BECS.Odata.Translator/api/odata/Customers?top=3&skip=1

Response:

 

2 How to use General BECS REST API Service in the project

​​​​​​2.1 General intro

Based on general architecture diagram listed in chapter 1.2.2 General architecture of BECS OData Service is possible to call any BECS project.

 

2.2 Sample of calling

For example calling Equipments from SAP PM module via BECS we used:

Request:

https://uks-dev-becs.bentley.com/BECS_Odata/api/odata/V-301/DATA_SAP_EQUI_Data

Response: