OData REST API — Small Useful Tricks (part 3)

Continuing a series of posts about the features of using OData protocol (see part 1 and part 2).

OData stipulates that the objects can be created and updated using standard HTTP request POST, PATCH and PUT. The request body should contain JSON description of the object that we want to update or add to the database.

If the object being added does not exist a new object is created.

If the object exists – the behavior is different:

• PUT – replaces the object with a new one
• PATCH – updates object fields with new values
• POST – behavior is not specified in the standard (in databoom POST is similar to PATCH)

4. Adding complex objects together with the linked objects

A few important phrases are lost in the text of the OData standard.

A request to create an entity that includes related entities, represented using the appropriate inline representation, is referred to as a “deep insert” … On success, the service MUST create all entities and relate them.

As a result, not everyone knows that OData enables you to add the objects with the child objects. For example, we can add a new book into the existing collection of books directly with its authors:

{

“id”: “book1”,

“title”: “Cannibal’s Cookbook”,

“author”:[

{

“id”: “person45”,

“collections”: [{ “id”: “persons” }, { “id”: “writers” }],

“firstname”: “John”,

“lastname”: “Doe”,

“age”: 69,

“likes”: [{ “id”: “book55” }, { “id”: “book19” }, { “id”: “book66” }]

},

{

“id”: “person191”,

“collections”: [{ “id”: “persons” }, { “id”: “experts” }],

“firstname”: “Lamar”,

“lastname”: “Courtenay”,

“age”: 37,

“likes”: [{ “id”: “book186” }, { “id”: “book18” }, { “id”: “book31” }]

}

]

}

In accordance with the standard, all the necessary objects will be created (or updated) and the links will be established between them. Then you can get a book, or a book with its authors; get the list of people (writers, experts), get people with their books, etc. (see. part 1, part 2)

5. Making connections between objects

1. Having the ability to add objects with embedded objects, you can easily establish links between them.

In the example above, we added the book with the author, who had the property ‘likes’

“likes”: [{ “id”: “book186” }, { “id”: “book18” }, { “id”: “book31” }]

In accordance with the standard all the books will be created (or updated if they already exist), and all the relationships will be established between persons and their favorite books. As soon as the books have only ‘id’ field, it is nothing to update, it is enough just to set up the links.

2. There is another way of setting up the links. List of favorite books of a person with id = ‘person191’ accessible via URL

…/persons(person191)/likes

We can add books by sending a request PUT, POST, or PATCH with this URL

Note: OData admits that an object can refer to many objects, and it can be referenced by many objects. For example, the book can have multiple authors as well as the author can write many books; a person may be a student and a teacher at the same time. Objects can belong to many collections at once.

If you are interested in this post, you can also look through our documentation, REST API usage examples, and examples of using JavaScript library.

To be continued…

OData REST API — Small Useful Tricks (part 2)

Continuing a series of posts about the features of using OData protocol (see previous post).

3. How to Filter the Objects Based on Their Relationships

Suppose we want to get a list of people who like the book titled (property ‘title’) ‘book36’ (such as a funny book title we have in the example).

To get all the people we can write

…/persons

It is easy to filter objects by properties. For example, to filter persons by age (a person has the property ‘age’):

…/persons?$filter=age gt 30 – all the people at the age > 30 years

But how do we filter the people by a field of another object, for example, the title of the book the man likes?

Very simple: a person has the property ‘likes’ referring to the book, and a book has the property ‘title’. So we can write:

…/persons?$filter=likes/title eq ‘book36’

If you are interested in this post, you can also look through our documentation, REST API usage examples, and examples of using JavaScript library.

In the next post we will tell you about adding complex objects along with the related objects, and about adding arrays of objects.

OData REST API — Small Useful Tricks (part 1)

OData protocol has many hidden advantages (as well as disadvantages). Starting with this article we would like to share with you some simple, useful tricks to using OData. All further examples use the following simple database schema.

• persons
• books
• companies

person properties:

• id (string)
• firstname (string)
• lastname (string)
• age (number)
• likes (list of books)

book properties:

• id (string)
• title (string)
• author (list of persons)
• publisher (a company)

company properties:

• id (string)
• name (string)
• president (person)

The database is available here. The data can be viewed using the OData URL (here).

1. How to get an array of objects that someone refers to

Suppose we want to get a list of books that a person likes.

We can do it through the following steps:

To get a person with id = ‘person1’,  we can write

…/persons(person1)

To get the books that the person likes, we’ll add “likes” property to the URL.

.../persons(person1)/likes

Now we can go even further and find all the publishers that published the books that person1 likes. …/persons(person1)/likes/publisher

2. How to get an array of objects referring to someone

In the previous example we got a list of books that person with id = ‘person1’ likes.

Now we want to get all the people who like the book with id = ‘book2’.

Note that the person through the property ‘likes’ refers to books he likes, but the books do not refer to the people who like them

To get a book with id = ‘book2’, we can write

…/books(book2)

We cannot write …/books(book1)/persons_who_like – the book does not possess the property ‘persons_who_like’

We can write

…/books(book1)/_backlink(likes)

_backlink(likes) – it is like a link back to the link ‘likes’

‘likes’ – what likes

_backlink(likes) – who likes

Some OData implementations assume that the developer has to arrange a pseudo property named, for example, ‘persons_who_like’ and write that request handler himself. _backlink operator is not a part of the standard, but may sometimes greatly simplify the work.

If you are interested in this post, you can also look through our documentation, REST API usage examples, and examples of using JavaScript library.

In the next post we’ll show you how to filter the objects based on their relationships.

Webix + databoom = rapid application prototyping

In this screencast we’ll show you how Webix and databoom can be used together for rapid development of application prototypes.

Webix – a set of JavaScript controls for user interface development.

Databoom – a cloud backend based on graph database.

Together they provide a cumulative effect. Webix enables you frontend development in a couple of lines of code, and databoom gives you a backend that is ready for use and very easy to use. As they say, “a picture paints a thousand words”

Thank you for attention, we are ready to answer your questions in the comments. The source code of the sample can be found here.

Announcement of databoom JavaScript library

Dear friends,

We have implemented the first version of JavaScript librarу that facilitates development of JavaScript code working with databoom.space service.

The library allows you to store and retrieve data, execute queries to the database in a few lines of code. For example:

var pers = [{ name: 'John' }, { name: 'Jane' }]
pers[0].wife = pers[1];
pers[1].husband = pers[0];
 
// Create a connection to your databoom database
var db = databoom('http://samples.databoom.space', 'sandboxdb');
db.save('persons', pers); //save data even with cyclic links

More details can be found here: databoom JavaScript Guide.

How JS Grid groups records using OData

In a previous article, we briefly described how a grid control communicates to a remote server using the OData protocol. The majority of modern grid controls allow convenient data grouping by several columns. Let’s consider what queries are generated by the grid and sent to a REST server when the grid performs automatic data grouping.

OData + Angular.js + Bootstrap + JavaScript Grid = application in 5 minutes

Suppose that you are developing a user survey Web application. The application would include the survey form (detailed form) and a form to view and edit the list of surveyed users (list form).

Let us consider the process of creating these forms using the following tools: OData, Angular.js, Bootstrap and JavaScript Grid. All of the necessary features have already been implemented in these tools, and we practically do not need to write anything.

How JavaScript Grid works with Odata protocol

In a previous post, we mentioned that:
There are many libraries today supporting OData protocol and new libraries arise every day.
In particular, the following JavaScript libraries work with OData: Kendo UI, DevExtreme Web, Syncfusion HTML5 controls, Infragistics HTML5 controls, OpenUI5, Wijmo, JayData, Breeze.js, datajs, ODataJS, angular-odata, etc.

Many of these libraries greatly simplify the complex applications development process thanks to OData standard. For example, it is sufficient for a GRID control to specify URL to OData Server. Everything else is performed automatically, such as paging, sorting, insert/update/delete the records, filtering, grouping, etc.

We’ve prepared some examples illustrating how grids work with OData.

• http://databoom.space/samples_kendo_ui_grid1.html – Kendo UI Grid.
• http://databoom.space/samples_kendo_ui_grid2.html – Kendo UI Grid with virtual scrolling instead of paging.
• http://databoom.space/samples_devexpress_grid.html – DevExtreme Data Grid.
• http://databoom.space/samples_syncfusion_grid.html – Syncfusion Grid.

Basic queries of a grid to the server:

• Get the total number of records that meet a certain condition
• Select the records to display on the page
• Get the entire record set
• Sort the records by one or more fields
• Filter records for a set of conditions
• Add a new record
• Modify the record
• Delete the record
• Batch update

Let us examine closely the basic requests using the example of interaction of Kendo UI Grid control and databoom (other grids function the similar way).

OData REST API and recursive queries

OData can perform recursive queries (functionality is similar to SQL CTE).

OData documentation (section 11.2.4.2) describes the query option $expand. That option allows for the retrieving of objects along with any linked objects. For example, you can acquire a company’s data along with its president’s data:

https://samples.databoom.space/api1/sampledb/collections/companies(company1)?$expand=president

Data management using OData protocol

Open Data Protocol (OData) is open Web protocol for querying and updating data. The protocol allows for the performing of operations on resources, requesting them via HTTP commands, and exchanging data in JSON or XML. OData is one of the best standards to create a RESTful API.

You can query the data using simple HTTP requests. For example:
https://samples.databoom.space/api1/sampledb/collections/persons?$filter=firstname eq ‘Lamar’ Find all people having first name Lamar

OData allows for the setting of a very large number of parameters, which allows one to form highly complex queries to the data source. For example:
https://samples.databoom.space/api1/sampledb/collections/books?$filter=publisher/president/likes/author/firstname eq ‘Georgie’&$top=10&$orderby=title Select all books satisfying the following condition: The president of the publisher that publicized the selected book likes the books of author named “Georgie”. The result should be sorted by the book titles, and the first 10 books should be displayed.

OData query language is comparable in power to SQL.