OData Server API

According to OData standard

URI schema

Principle of building URI of OData Server complies with OData specification.

http://services.odata.org/OData/OData.svc _______________________________________/
  | service root URI 
http://services.odata.org/OData/OData.svc/Category(1)/Products?$top=2&$orderby=name
_______________________________________/ __________________/  _________________/
                   |                                |                    |
            service root URI                  resource path        query options

Service Root URI

Conforms to the OData specification.

Addressing Entries

Partly сonforms to the OData specification:

  • Get a collection of entities - conforms.
    (example: "http://services.odata.org/OData/OData.svc/Categories")
  • Get an entity by key predicate - conforms.
    (example: "http://services.odata.org/OData/OData.svc/Categories(1)")
  • Get an attribite value of entity - does not conforms.
    (example: "http://services.odata.org/OData/OData.svc/Categories")
    It's supposed to perform this request by parameter $select
  • Get a related entity - does not conforms.
    It's supposed to perform this request by get the target entity directly (by key predicate).
  • Get a collection of related entities - does not conforms.
    It's supposed to perform this request by get the target entities collection directly.

Addressing Links between Entries

Requesting related entities by parameter $link - currently is not implemented.
It's supposed to perform such a requests directly to the collections or instances of target entities.

Addressing Service Operations

Next base service routes are inmplemented:

  • [service_root]/$metadata - get service mrtadata.
    Supported formats are XML/Atom and JSON.
  • [service_root]/ - get list of available collections and routes of service.

Invocation of stored procedures execution is performed according to paragraph Invocation of stored procedures of this document.

Using OData request parameters

Parameter $orderby

Rules and result of using this parameter conforms to the OData specification.

Parameter $top

Rules and result of using this parameter conforms to the OData specification.

Parameter $skip

Rules and result of using this parameter conforms to the OData specification.

Parameter $filter

Rules and result of using this parameter partly сonforms to the OData specification.
At this moment next expression-predicates are supported:

  • bool substringof(string po, string p1);
  • bool endswith(string p0, string p1);
  • bool startswith(string p0, string p1).

Next logical operators are supported:
  • Eq (Equal);
  • Ne (Not equal);
  • Gt (Greater than);
  • Ge (Greater than or equal);
  • Lt (Less than);
  • Le (Less than or equal);
  • And (Logical and);
  • Or (Logical or);
  • Not (Logical negation).

Next arithmetic operators are supported:
  • Add (Addition);
  • Sub (Subtraction);
  • Mul (Multiplication);
  • Div (Division);
  • Mod (Modulo).

Parameter $expand

Rules and result of using this parameter conforms to the OData specification.

Parameter $select

Rules and result of using this parameter conforms to the OData specification.

Supported data formats

At the moment next OData data formats are supported:

  • Xml ($format=xml);
  • JSON ($format=json).
Furthermore, additional data format is implemented: $format=simplejson.
Feature of this format is returning request result as a flat array of data (not a hierarchical structure).

Additional features

Parameter fillnavproperties

Parameter fillnavproperties is designed to automatical filling foreign key fields with values of related entities.
Entity field marked with special word "DisplayName" is used as a supplied value of related entity.
Using MySQL database it's supposed to fill "Comments" field of target entity property.
Example of using "DisplayName" field with MySQL database: Define entity display name field with MySQL database


Using MS SQL database it's supposed to fill "Description" field of target entity property.
Example of using "DisplayName" field with MS SQL database: Define entity display name field with MS SQL database

Invocation of stored procedures

Stored procedures enabled to invoke are detected by OData Server automatically when starting it.

Route of stored procedures invocation

Invocation of stored procedures is performed on route with mask [OData Server root host]/Invoke/[SP name].
For example: http://ODataServerHost:8005/Invoke/GetPersonsByAge?Age=20

Pass parameters

Parameters of stored procedure could be passed in request string or in request body.

Passing parameters in request string

Parameters are passed in request string according to the next rule: ?[IntParameter]=[10]&[StringParameter]='[StringParameterValue]'.
Values of string parameters should be escaped with single quotes.
Example of invocation of stored procedure with passing parameters in request string: http://ODataServerHost:8005/Invoke/GetPersons?Age=20&NameEntry='Jo'

Passing parameters in request body

Parameters are passed in request body as the object of the following form:
{
    "par1Name": "par1Value",
    "par2Name": "par2Value",
    "par3Name": "par3Value"
    ...
}

Handle execution result

If a stored procedure returns dataset, then OData Server places to the response body the serialised to JSON array of received records.
Example of execution result of stored procedure, that returns dataset, is shown below. Result of invocation of stored procedure by OData Server

API of access management component

Action Route Passed parameters Response example
Login {ODS.RootHost}/Login var loginReqPars = {
   Login: "admin",
   Password: "111111"
}
"QWRtaW46MTExMTEx" //Authentication token
Change password (by user itself) {ODS.RootHost}/UpdateMyPassword var updateMyPassReqPars = {
   UserLogin: "admin",
   NewPassword: "123456"
}
"User password was updated sucesfully."
Get list of users {ODS.RootHost}/GetAllUsers No parameters are passed [{ "UserID": 1,
   "Login": "Admin",
   "EMail": "",
   "LastName": "",
   "FirstName": "",
   "MiddleInitial": "",
   "PhoneNumber": "",
   "RolesList": "Admin"
},
{
   "UserID": 2,
   "Login": "user1",
   "EMail": "asd@asd.com",
   "LastName": "asda",
   "FirstName": "dasdas",
   "MiddleInitial": "dad",
   "PhoneNumber": "",
   "RolesList": ""
}]
Create user {ODS.RootHost}/CreateUser var createUserReqPars = {
   Login: "john",
   Email: "mail@mail.com",
   LastName: "Smith",
   FirsName: "John",
   MiddleInitial: "Jay",
   Passord: "111111",
   ConfirmPassword: "111111"
}
4 //ID of created user
Edit user {ODS.RootHost}/UpdateUser var updateUserReqPars = {
   UserID: "2",
   Login: "NewLogin",
   Email: "somemail@gmail.com",
   LastName: "Simpson",
   FirstName: "Homer",
   MiddleInitial: "Jay",
   PhoneNumber: "+79457520963",
   RolesList: "Admin,AnotherRole"
}
"User was updated successfully"
Delete user {ODS.RootHost}/DeleteUser var deleteUserReqPars = {
   UserID: "5"
}
"User 5 was deleted sucesfully"
Get list of all roles {ODS.RootHost}/GetAllRoles No parameters are passed [{
   "RoleID": 1,
   "Name": "Admin"
}, {
   "RoleID": 2,
   "Name": "manager"
}, ... ]
Create role {ODS.RootHost}/CreateRole var createRoleReqPars = {
   Name: "New role"
}
2 //ID of created role
Edit role {ODS.RootHost}/UpdateRole var updateRoleReqPars = {    RoleID: "2",
   Name: "New name role"
}
"Role was updated sucesfully"
Delete role {ODS.RootHost}/DeleteRole var deleteRoleReqPars = {
   RoleID: "3"
}
"Role 3 wad deleted sucesfully"
Get list of users's roles {ODS.RootHost}/GetRolesByUser var getRolesByUserReqPars = {
   UserID: "2"
}
1,3 //List of role IDs, applied to user, joined by comma.
Apply roles to user {ODS.RootHost}/ApplyUserRoles var applyUserRolesReqPars = {    UserID: "2",    RoleIDsList: "1,3" } "Roles applied sucessfully"
Get permissions list for role {ODS.RootHost}/GetRolePermissions var getRolePermissionsReqPars = {
   RoleID: "2"
}
[{
   "RoleID": 3,
   "PermissionID": 1,
   "TableName": "Company",
   "ActionName": "GetListOf",
   "IsEnabled": true
},
{
   "RoleID": 3,
   "PermissionID": 2,
   "TableName": "Company",
   "ActionName":"Delete",
   "IsEnabled":true
}, ...]
Apply permissions for role {ODS.RootHost}/ApplyRolePermissions var applyRolePermissions ReqPars = {
   RoleID: "2",    EnabledPermissionsIDsList: "1,2,3,6"
}
"Permissions applied sucessfully"
Get all available permissions {ODS.RootHost}/GetAllPermissions No parameters are passed [{
   "PermissionID": 1,
   "TableName": "Company",
   "ActionName": "GetListOf"
},
{
   "PermissionID": 2,
   "TableName": "Company",
   "ActionName":"Delete"
}, ... ]