OSI POST Request
An OSI POST request executes an OSI expression or an OSI access path for evaluating the source property and returns a JSON response. An OSI request allows retrieving data but also updating database content.
http://server:port/osi
body
The URL for an OSI POST request only contains the keyword osi (not case sensitive). The request is passed in the body of the OSI POST request
body: The OSI POST request is passed in the body with following structure (see Symbol reference / body - request data for OSI POST):
source => { fieldlist }
source - The source property defines the data source for the request, i.e. the vertical dimension of data to be processed. A source property may refer to an elementary data item, to an instance or to a collection of instances. In case of including functions in the source expression, the function result represents the source property for creating the result. Following source definition formats are supported:
- access path - is a valid OSI access path for the database. Usually, an access path consists of extent or property names and function calls. Access path elements are separated by dot (.), e.g.
Persons().income('netto') or
Persons("ID123").income('netto') ).
- function - is a valid OSI inline function enclosed in { ... }.
- expression - Expressions are valid OSI expressions (access paths combined with operations)
Access paths, functions and expressions have to be defined within the context of the database.
fieldlist - An OSI POST request returns data for an elementary data item (value), an instance (object) or a collection (array). In case of complex data (complex data type for source property), the field list defines the horizontal result dimension (object elements). In case of referring to an elementary data type source property, field lists are not supported and will cause an error. A field list allows reducing the number of values returned from an instance but also adding derived or related information. Moreover, field definitions allow defining hierarchical response structures. A fieldlist contains one or more field definitions separated by comma:
fielddef, ..., fielddef
fielddef - Field definitions may be provided in different ways:
- name - Name of a property defined for the data type of the preceding (upper) source. In this case, the value name in the response is the same as the property name. In order to rename the value in the output, one may define name: source, where name is the value name in the response and source is the property name for the value to be assigned..
- name: source - In order to return fields in the response that are not defined for source property (related or derived information), one may pass a source definition as access path, function or OSI expression (see source definition above).
- name: source => { fieldlist } - In order to define hierarchical response, one may define a source (see definition above) appended by a field list.
Sources in field lists have to be defined within the context of the preceding (upper) source, i.e. when the source returns a Person property, field sources must refer to access paths or inline expressions valid in the context of Person.
When the defined source is an elementary property, a field list must not be defined and the item is returned as value. When source defines an instance or collection without defining a fieldlist, the part of the response for this source corresponds to the response of a GET request.
In case of errors in the request definition or while executing the request, an error description is returned as JSON object (see Error handling) in case of error(s).
More details about source and fielddef syntax are provided in Symbol reference / body - request data for OSI POST. How to define OSI access paths, functions and expressions is described in ODABA Script Interface.
// OSI POST body
Persons('ID123') => {
name: { name + ', ' + first_name; }, // inline function
employed_at: employees(0).company(0).name, // access path
children: children => {
name: name + ', ' + first_name, // expression
loid: instanceLoid,
age
}
}
The OSI POST request returns a JSON object (syntax of object and other syntax elements referenced here is described in chapter Symbol reference). In case of error, a string_value is returned containing an error message. The response for a successful OSI POST request is an object with one named_value:
{ name: values }
An OSI POST request may define a request hierarchy. Here, the response structure for a request with one hierarchy level is discussed, which is repeated for all deeper levels.
The top element name is the name of the source property. For a subordinated source definitions, which are always part of a fielddef in a field list, the name of fielddef is used.
The structure of values following name depends on the complexity of source. values for collection properties and array attributes with complex data type are returned as array of object(s):
name: [ object, ..., object ]
name: [ ]
When the collection property is empty, [] is returned as empty array. For elementary array attributes an array of values is returned:
name: [ value, ..., value ]
For a single complex data type property an object is returned:
name: { named_value, ..., named_value }
For an elementary source property (elementary attribute, MEMO or BLOB), a value is returned:
name: value
When returning an object, named_value(s) within the object are, usually, names listed in the fieldlist for the source. When no field list has been defined, all properties of the complex data type are included (same as for GET). For collection properties within returned instance(s) , an array of URL objects is returned (see GET response).