OrientDB Intro & HTTP REST API Tutorial

An E-Commerce Case Study Walkthrough

Data access is a foundational consideration of any software application.

Should your data be stored locally or in the cloud? Is it currently organized and logical, or is it a mess of database tables which require several requests to construct a meaningful interface?

If you and your team face these questions day-to-day, you’ll want to read on.

Only interested in the API portion of this tutorial? Feel free to jump to that section below…

These days with our iPhones and IoT devices, data access on the go is what brings real power to our cutting edge apps.

If you’re a developer, you know that an HTTP REST API is the standard for communicating data online, and is practically a requirement of any internet technology.

As our devices get faster and our applications get bigger and more complex, this interface can often be the chokepoint slowing down our applications, and is therefore becoming an increasingly important piece of our stack to master.

https://www.programmableweb.com/news/programmableweb-api-directory-eclipses-17000-api-economy-continues-surge/research/2017/03/13

So, how do we handle this problem?

We must be careful about the technologies we choose to power our applications, from the data layer all the way up.

As a developer myself, I’ve worked with a variety of technologies, from IBM enterprise platforms to iOS mobile apps. With each new project I need to choose a reliable and fast database solution to fuel my applications.

Lately, OrientDB has been my go-to database of choice. Here, I’ll walk you through how to use it and it’s HTTP REST API.

http://orientdb.com/

E-Commerce Case Study

Many times I find that a case study is easiest to walk through a technology.

Recently, I have been developing e-commerce applications and web apps, and I think illustrating how better technology can literally make you more money (and save a lot of headaches) will help anyone understand the power of OrientDB.

So, let’s say we’re going to sell electronics online… we’ll call it “ComputerStore” =)

For the sake of readability, I’ll keep it simple.

ComputerStore

We’ll say our store has different types of devices, including laptops, phones, and computer parts. These may be components of each other, some may be compatible, and some may not. Visitors to our site can make purchases and enter in their payment and shipping information. We may want to view a past order, and know what item we bought.

Let’s say those devices are going to be an Android phone, a MacBook laptop, and a Dell desktop. All of those have memory components, but of different sizes, and the phone and the laptop have an accelerometer.

For the less technical, what I just described above are a series of “requirements” or user stories for our simple application. Now image the requirements necessary to support a major brand name’s e-commerce website.

Enterprises literally need documentation of their documentation to keep track of everything. These data models get pretty complex, to say the least.

Thankfully, we’ll see how OrientDB simplifies many of these relationships. Here’s what our data model will look like soon:

That graph above is probably a much easier way to understand the store we have planned. The circles indicate products in our store, and those arrows represent the relationships between our products.

Here, you can already visualize the value in a graph database, such as OrientDB, versus a traditional relational database. Tables are nice, but not when we get to the production level.

Let’s build this data model in OrientDB.

Wait! Need to know how to get OrientDB up and running? Check out this Udemy course: https://www.udemy.com/orientdb-getting-started/

Schema…

Our products need to have some more information, such as their prices, a description, and an image that we can display on our store. We’ll choose a few products to stock our store with here

Here’s a spreadsheet of the data we’ll plan to use:

https://docs.google.com/spreadsheets/d/18dZZocfEXmP8Z5Pi1-fgoSvI7Z89rzNXY0RHC7sEHZA/edit?usp=sharing

Start up your OrientDB server and launch the OrientDB Studio editor by navigating to http://localhost:2480 in a web browser.

Using the Schema Manager page, create a new vertex and name is Products. You’ll see it appear under Vertex Classes.

Select our new Products vertex, and once inside, create a new property for each of the attributes in our spreadsheet.

That’ll be:

  • Price: Double
  • ProductDescription: String
  • ProductImageURL: String
  • ProductName: String
  • ProductNameShort: String

Next, create the Orders vertex with the following properties

  • TotalPrice: Double
  • ShippingInformation: String
  • PaymentInformation: String

Lastly, we’re going to use the built-in OUser system class to represent our users. When a visitor registers with our store we’ll give them an option to store their payment and shipping information.

By default, OUser is a document. We’re going to use it as a vertex, so we’ll need to alter it and then add those properties.

Execute the following command:

ALTER CLASS OUser SUPERCLASS V

And then add properties to OUser for:

  • Address: String
  • PaymentInformation: String
  • FullName: String

This is a good time to mention that OrientDB is a multi-model database which supports relational, graph, key-value, and document database styles. That’s a really powerful feature that deserves some deeper reading here. The TL;DR is that it can support different access patterns and logical representations depending on what makes the most sense for each system and interface that’s talking to it.

Relationships

Next, we’re going to represent the relationships between our products, an order, and a customer, using graph edges.

Graph edges represent a directional relationship. Here, we’re going to say Products can be Components other Products. Orders ItemInOrder is the Product that was purchased, and OUser customer HasOrder to an Orders record.

Following along? Feel free to refer back to our earlier graph graphic.

From the Schema Manager, select + NEW EDGE

Create these Edges:

  • Components, From: Product, To: Product
  • CompatibleWith, From: Product, To: Product
  • HasOrder, From: OUser, To: Orders
  • ItemInOrder, From: Orders, To: Products

Then, we’ll populate our edges by connecting them in the OrientDB Studio’s Graph Editor, which has a great interactive interface to plug our nodes into each other.

To start, navigate to the Graph tab, and then enter SELECT from PRODUCTS. You’ll see nodes for all of the devices we entered. To make this easier to read, click on one of the nodes and hit the properties button. Then toggle over to the Settings tab on the left-side menu to change Display: ProductNameShort.

Select the nodes and hit the create edge button, which looks like a link or chain icon. An arrow will show, which you’ll drag to the other corresponding node. Then a pop-up will display where you can select the class of edge for each relationship.

Perfect, now one more thing we’ll need to do before we dive into the HTTP REST API is to define a server-side function for creating orders. Making a purchase can be a multi-step operation that includes sensitive information, such as credit card information, much of which is best handled server-side.

We’ll keep our case study simple, but follow this best practice. OrientDB allows the definition of Server Side Functions using JavaScript, Groovy, and SQL, which can all be programmed in the Functions Management interface. Read more about OrientDB’s server side programming here: https://orientdb.com/docs/2.2/Functions-Server.html

We’ll name the function CreateOrder and set the language to javascript. Select + PARAMETER to accept inputs for ProductID and BuyerID.

Grab our CreateOrder code below or at this Gist link. Server side functions could be a lengthy tutorial on their own someday!

https://gist.github.com/ablatner88/4ed7781c4370b01404fac05de89a7630.js

OrientDB’s RESTful HTTP API

Great, now our database should be ready to go. Trust me, that setup was pretty easy compared to many other tools and enterprise platforms I’ve used in the past.

Now we can start interacting with our server through OrientDB’s RESTful HTTP API. This is available right out of the box with no more configuration or programming needed.

Now, let’s say we’re planning to build a public website or mobile app which customers will use to browse and make purchases from our store.

What are the API endpoints that we’ll want to use?

  1. A user arrives at our store and wants to sign-in. (Connect)
  2. A user views our catalogue of products. (Products)
  3. A user drills down to view the components of a product. (Components)
  4. A user decides to make a purchase. (CreateOrder)
  5. A user wants to see their orders. (Orders)

In this tutorial we’ll use the Chrome app, Postman, to simulate interactions with our OrientDB HTTP API. If you’re not using the Google Chrome browser, you’ll have to use another HTTP client.


Connect (A user arrives at our store and wants to sign-in.)

GET http://{{server}}:{{port}}/connect/{{database}}
GET http://localhost:2480/connect/ComputerStore

This method connects to a remote server using basic authentication. It verifies that our server and database exist, and that our user is properly logged in.

A successful request will just give us back a 204 OK.


Products (A user views our catalogue of products.)

GET http://{{server}}:{{port}}/query/{{database}}/{{language}}/SELECT from PRODUCTS
GET http://localhost:2480/query/ComputerStore/sql/SELECT from PRODUCTS

To get our list of Products, we’ll query our database passing in an SQL SELECT statement.

Keep in mind, if you have a large database, such an enterprise store, you’d probably want to add additional filters or limit the number of records returned.

We receive a JSON response containing an array result object. That result object is a list of our Products records, containing a dictionary of our properties, such as @rid, ProductName, and Price. Which is the data we need to render our store’s catalogue to our customers.

Want to see it another way? With your server running on localhost, type the following into your web browser:

http://admin:admin@localhost:2480/query/ComputerStore/sql/SELECT from PRODUCTS

Components (A user drills down to view the components of a product.)

GET http://{{server}}:{{port}}/query/{{database}}/{{language}}/SELECT expand(out(‘Components’)) from <<@rid>>
GET http://localhost:2480/query/ComputerStore/sql/SELECT expand(out(‘Components’)) from 23:1

Here, we’re traversing through the edges of our graph database to retrieve the related products that we want to display to the user. These edges have in and out properties, which are Type:LINK, aka the @rid numbers of the products we want to display.

So, say we are viewing our Apple MacBook product, which is @rid=#23:1. The Apple MacBook has two Out Edges of type Components, with @rids of #31:1 and #32:1, which link to #23:2 (Accelerometer) and #22:3 (8 GB Memory), respectively.

This request allows us to traverse from our Apple MacBook to Accelerometer and 8 GB Memory.


CreateOrder (A user decides to make a purchase.)

POST http://{{server}}:{{port}}/function/{{database}}/{{name}}/{{argument1}}/{{argument2}}
POST http://localhost:2480/function/ComputerStore/CreateOrder/23:1/5:0

Now we want to execute our server-side function that we had previously defined through the OrientDB Studio Functions Management interface, called CreateOrder with parameters ProductID and BuyerID.

In our store example, when a customer clicks purchase on one of our products, we’ll execute the CreateOrder function, passing in the @rid for that product, and the current user’s @rid as well.

Note that this is a POST request, since our function will be creating records and is not idempotent.

In Postman, a successful invocation will display the “success” response we defined in our function.

Which creates the following in our graph view of the database:


Orders. (A user wants to see their orders.)

GET http://{{server}}:{{port}}/query/{{database}}/{{language}}/SELECT expand(in) from HasOrder where out = <<@rid>>
GET http://localhost:2480/query/ComputerStore/sql/SELECT expand(in) from HasOrder where out = 5:0

Once a user makes a purchase, we imagine they’ll want to be able to see their past orders and details of what they’ve purchased.

So, we’ll retrieve existing orders tied to our current user’s @rid.

In the data model we’ve created, there’s many ways to retrieve these records. Given our user ID, we’ll follow our HasOrder edge to the associated Orders.

Selecting the IN property of the edge will give us an @rid and applying expand(…) to that property gives us the actual record for that @rid.

More resources

Great, if you’ve followed along our tutorial through everything — congrats! You’ve learned a bit of background on multi-model databases, HTTP REST APIs, and the power of OrientDB.

We’ve just scratched the surface here into what’s possible. OrientDB is capable of supporting enterprise applications that are many magnitudes more complex in terms of schema, relationships, and datatypes.

Most of our interactions here were retrieving data from the database. OrientDB implements role-based access and security features to enforce access rules that you may want to leverage. These are useful to limit certain sensitive data and sensitive functions to users with the right level of access, such as admins.

Here are a few resources available for additional reading. There’s a lot of good documentation on OrientDB’s website and helpful colleagues on the Internet. Good luck!