BSL OData Interface

What is OData?

 

OData (Open Data Protocol) is an ISO/IEC approved, OASIS standard that 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. OData also provides guidance for tracking changes, defining functions/actions for reusable procedures, and sending asynchronous/batch requests.

www.odata.org

 

OData RESTful APIs are easy to consume. The OData metadata, a machine-readable description of the data model of the API, enables the creation of powerful generic client proxies and tools.

The Beas Service Layer supports ODATA versions 2, 3 and 4 with limited compatibility. For compatibility information, see the descriptions below.

 

youtube What is OData, main information about collection, $select, $filter and $orderby commands

youtube Differences between ODATA2 and ODATA4 in view of BSL

youtube OData $expand command. join objects

youtube OData $format command, export types

youtube OData $skip and $top commands, web page handling and $inlinecount command

youtube OData $batch command. Execute more then one GET command with one Internet request

youtube OData $union command

youtube OData $transaction command

youtube BSL Customization: Add own columns, functions and objects

 

 

Syntax of OData

Collection -> [ (KeyPredicate) ] -> FieldName
Collection -> [ (KeyPredicate) ] -> FieldName/$value   (or $sum, $min, $max, $avg, $count)
Collection -> [ (KeyPredicate) ] ?[Property]&[Property]&[Format]

 

Area

Description

Collection

The name of a collection.

Example: Item, BusinessPartner

KeyPredicate

A predicate that identifies the values of the key properties of an entry.

Example:

Item("A001") returns all fields for an item or Item(ItemCode="A001")

odata-adressing2

FieldName

Returns one set of data.

Example:

Item/ItemCode returns the item code for all items in the defined format.
Item("A001")/ItemName returns the item name for Item A001 in the defined format.
Item("A001")/ItemName/$value returns the raw text value of the item. It returns the first result only.

 

Compatibility:

Sub-objects, for example Item("A001")/UoM/UoMName, are not allowed.

Query Options

Property keys, like $select, $filter. For example, /Item?$filter=ItemName eq 'Sofa'.

Format

Defines the output format. For example, Item("A001")/ItemName?$format=html

 

Query Options

The system query options are query string parameters, that a client may specify to control the amount and order of the data that an OData service returns for the resource identified by the URL. The names of all system query options are prefixed with a $ character (ODATA4).

An ODATA service may support some or all of the defined system query options. If a data service does not support a system query option, it must reject any requests that contain an unsupported option.

The semantics of all system query options are defined in the ODATA:Core document.

The grammar and syntax rules for the system query options are defined in the following table.

 

Keyword

Description

$filter

The set of entities returned may be restricted with the $filter system query option

$expand

Specifies the related entities to be included

$select

Requests a limited set of properties for each entity

$orderby

The $orderby system query option specifies the order in which entities are returned from the service

$top

The $top system query option specifies that only the first n records should be returned

$skip

The $skip system query option specifies that the result must not include the first n entities

$inlinecount

Returns the total count of rows

$count

The $count system query option requests only the count of an entity collection

$format

The $format system query option, if supported, allows clients to request a response in a particular format.

$batch

Execute more than one GET command (not ODATA Standard format)

$union

Define a second get command, which is added to first one

$grouby

Simple group by function

$metadata

Return the Metadata from Service Layer

Special Beas properties

Keyword

Description

$mask

Define a mask for drop-down tables (beas script)

$branch=<num>

Switches to the specified branch and BSL displays results only related to this branch

$transaction=<string>

Filters for a transaction type and BSL returns only those results, that are allowed for this transaction type

$ProgramId

Define the ProgramId, for example "terminal2". This is mandatory, if you use ODATA via WEB APP.

When working with a UX Library, the following syntax can be used: $ProgramId='+appInfo.gid+'&$AppId='+appInfo.appID

$AppId

Define the App name. This is mandatory if you use ODATA via WEBAPPs

When working with a UX Library, the following syntax can be used: $ProgramId='+appInfo.gid+'&$AppId='+appInfo.appID

asynch=true

The system sends a command to the Common service.

 

Function calls

 

Common Response Semantics

 

Response JSON Format

Reference: http://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html

 

Format

Command

Result

Representing a property in a response

Item("A001")

{
   "CustomerName": "the value of the property"
}

Representing multiple entities in a response in ODATA version 2

 

ODATA2/Item?$inlinecount=allpages

{
"__count": 37,
"results": [ { ... },{ ... }, { ... }
    ],
}

Representing multiple entities in a response in ODATA version 4

ODATA4/Item?$inlinecount=allpages

{
"@count": 37,
"value": [ { ... },{ ... }, { ... }
    ],
}

Working joins and the $expand function

 

The join object is exported as a sub-object (JSON array).

Item("A001")
?$select=ItemCode,UoM/UoMCode
&expand=UoM

{"value":
"ItemCode: "A001",
  "UoM": {"UoMCode":"Pcs"} ]
}

Working joins without the $expand function

 

The response is returned all as one object.

Item("A001")
?$select=ItemCode,UoM/UoMCode

{"value":
"ItemCode: "A001","UoMCode":"Pcs"
}

 

Keywords

odata2

odata3 and 4

Description

results

value

Returns the result.

__count

@count

The name/value pair representing the $inlinecount. The value must be an integer corresponding to the total count of members in the collection represented by the request. If this is present, this name/value pair must come before the result name/value pair.

 

Representing Errors in a Response

The error response is a single JSON/XML object. This object has a single name/value pair. The name is error and the value is a JSON object.

The JSON object can have two or three name/value pairs with the code names and messages.

If the value for the code name/value pair is a string, it is a service-defined error code. This code serves as a sub-status for the HTTP error code specified in the response.

If the value for the message name/value pair is an object, the object has two name/value pairs, with names lang and message. The message name/value pair contains a human-readable representation of the error. The lang name/value pair contains the language code from RFC 4646 corresponding to the language in which the value for message is written.

If the value for the inner error name/value pair is an object. The contents of this object are service-defined. This object usually contains information that helps debugging the service.

 

{
    "error": {
        "code": "A custom error code",
        "message": {
            "lang": "en-us",
            "value": "A custom long message for the user."
        },
        "innererror": {
            "trace": [...],
            "context": {...}
        }
    }
}

 

 
 

Attributes

Name

The name attribute allows a name to be assigned to the property.

Type

Structural types are composed of other structural types and primitive types. CSDL defines the following fully qualified primitive types:

Edm.Boolean

Edm.DateTime

Edm.Decimal

Edm.String

Edm.DateTimeOffset

Nullable="true/false"

The value of this attribute determines whether a value is required for the property for instances of the containing type.

If no value is specified, the nullable facet defaults to true.

MaxLength="x"

The value of this attribute specifies the maximum length of the value of the property on a type instance.