oData-api-introduction

The OData Web API has been implemented to be compliant with the standard OData V4.0 protocol.

The Open Data Protocol (OData) is a protocol that allows data to be shared via Atom or JSON formats. This protocol allows creation and consumption in RESTful. In other words, it allows a web client, from simple HTTP messages, to publish and edit resources identified in the URL and defined in the LMS data model.

• Learn more: http://www.odata.org/documentation/

• Regarding our Web API, the Endpoint (or entry point) is as follows: odata-api.

• As a result, all URLs using the OData API will start like this: https://host/odata-api: ("host" being the name of the server.).

• Not all functions of the OData standard are implemented in our API. Consult the "Implementation" chapter for details.

• This document does not take into account any customisations made to the entity fields. The description of properties made in this document is the description of the properties as standard.

Vocabulary

The Syfadis application is made up of "entities" that intelligently organise and record the data of the LMS.

• An "entity " describes information about an object such as a user, a course, a session, etc.

• Each column of an entity is called a "property".

• An entity can have multiple properties.

Some of these properties can be other entities or entity collections. This is called " navigable property". You must then use the enlargement option to access them in detail and perform link operations between objects to manipulate them.

An "exposed entity" is an entity that is made available by the OData Web API.

• The exposed or non-exposed nature of an entity can be verified by consulting the $metadata.

• "Users" is an entity defined in Syfadis and exposed in the Odata Web API that contains the information of LMS users in the company.

• The "Users" entity has properties such as FirstName, LastName, Address...

• The "User" entity has navigation properties such as Domains, Structures.

Exposed entities

Exchange Format

Syfadis only implements the JSON data exchange format.

The only element that is not expressed in JSON is the metadata file which is expressed in XML.

JSON is a lightweight data exchange format that is both easily editable and human-readable but also simple to interpret and generate by machines. It is language-agnostic and uses conventions that are familiar to the majority of developers. JSON interpreters are already available for almost all programming languages. These properties make JSON an ideal language for data exchange.

Learn more here: http://www.json.org

Query options

OData supports many kinds of query options.

The following are the query options implemented by Syfadis.

Warning: Entity names and property names used in URLs are case-sensitive. An error in the case of an entity leads to a 500 error with in the message body "The controller for path '/odata-api/xxx' was not found or does not implement IController."

Filtering ($filter)

The $filter option allows you to filter a collection of entities.

The expression specified by the "$filter" is evaluated for each resource in the collection. Only items that meet the specified condition are returned.

Filtering on a property of the requested object:

/odata-api/Users?$filter=FirstName eq 'Peter'

/odata-api/Users?$filter=contains(Name,'Pier')

/odata-api/Domains?$filter=Father0 eq null

/odata-api/Users?$filter=FirstName eq 'Pierre' and DeletedOn eq null

Filtering on a collection subproperty with the ANY and ALL operators:

/odata-api/TrainingSessions?$filter=Tutors/any(it:it/Domains/any(d:d/Name eq 'France')) (filters sessions with at least one instructor in the France domain)

/odata-api/TrainingSessions?$filter=Tutors/all(it:it/Domains/any(d:d/Name eq 'France')) (filters sessions where all instructors must belong to the France domain)

Filtering on subproperties:

/odata-api/TrainingSessions?$filter=Training/OptionalEnumField2 eq '100'&$expand=Training (filter on sessions whose training has an OptionalEnumField2=100)

Not all filtering options are listed in this document. For a detailed description of the possibilities, see the links below:

http://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part2-url-conventions/odata-v4.0-errata03-os-part2-url-conventions-complete.html#_Toc453752358

Order ($orderby)

The $orderby option allows you to sort a collection of features, in ascending or descending order.

If the precision of the order is not specified, then the collection is sorted in ascending order. Finally, if the sort order option is not specified, the data is sorted in ascending order on the id.

/odata-api/Users?$orderby=LastName

/odata-api/Users?$orderby=LastName desc

Combination of the " filter " option + the " order by " option.

/odata-api/TrainingSessions?$orderby=StartedOn&$filter=StartedOn gt 2018-01-01T00:00:00Z and StartedOn lt 2018-03-08T23:00:00Z

Top and skip

The $top option allows you to retrieve only the n 1st entities of the collection.

The $skip option allows you to ignore the n 1st entities of the collection and retrieve all the following entities (jump).

/odata-api/Users?$orderby=LastName desc&$top=5&$skip=2

Count

The $count option allows you to count the entities that result from the query, and return that number instead of the collection.

/odata-api/Users/$count

Expand

The $expand option expands the navigation properties of the response to include dependent entities. (In connection with the main entity).

The following query returns users while including the Domains and Jobs navigation properties:

/odata-api/Users?$expand=Domains,Jobs

Selection

The $select option allows you to limit the number of properties returned.

To select a property of the requested object:

/odata-api/Users?$select=FirstName,LastName

Sub-property selection:

/odata-api/Trainees?$select=LmsProgress&$expand=User($select=Code),TrainingSession($select=FinishedOn;$expand=Training($select=Name) )—Selecting the enrolment progress, the user code registered for the session, the session end date, and the training name.

Example of using combined selections and filters:

/odata-api/Trainees?$select=LmsProgress&$expand=User($select=Code),TrainingSession($select=FinishedOn;$expand=Training($select=Name))&$filter=User/Code eq 'XXX' and (LmsProgress eq 'NotAttempted' or LmsProgress eq 'Incomplete') and RegistrationOrigin eq 'BackOffice' and TrainingSession/DeletedOn eq null and DeletedOn eq null

Functions on " text " properties

The following functions can be used in select queries on " text " properties:

• tolower: Converts the value of the passed property to a lowercase parameter.

• toupper: Converts the value of the passed property to an uppercase parameter.

• trim: Removes the leading and trailing spaces in the value of the property passed as a parameter.

Examples :

/odata-api/Trainings?$filter=toupper(Code) eq 'A001'

/odata-api/Trainings?$filter=toupper(trim(Code)) eq 'A001'

/odata-api/Trainings?$filter=contains(tolower(Code),'a001')&$expand=PrimaryDomain

Unsupported operations

Server-driven paging is not supported for partial return results. We recommend the use of the $top and $skip primitives to handle paging.

• The $search search option is not supported.

• The IN operator is not supported.

• UPSERT operation is not supported.

• HTTP requests for PUT entity updates are supported, but they are interpreted as a PATCH. This is to prevent possible unintentional data loss. (https://issues.oasis-open.org/browse/ODATA-274). However, the PUT complies with the standard as part of a simple link update.

• Raw value retrieval by adding a $value to the end of a URL is not supported.

• Batch operations are not supported.

Learn more

Security and authentication

OData entity management

Studio Contents

OData API - Appendix