A few months back I wrote a thorough tutorial on how to use
the Couchbase Java SDK to create an application
around the Couchbase 4.0 sample data. However, I never explained the thought process
behind developing such an application or why the Couchbase Java SDK is so convenient.

With this article I plan to walk through the thought process behind designing an application and then
how you might develop it with Java and Couchbase. Of course it won’t be as thorough as my tutorial, but viewing them
together will definitely put you on the right track.

Crafting a Design Process

Let’s assume you want to build the next great travel booking application. You’ve got the great idea,
but aren’t sure what kind of process to follow for executing the idea. It is probably a good idea
to break the idea up into parts.

More than likely your travel booking application will contain the following three parts:

  • A backend API layer
  • A client-facing UI layer
  • A data layer

So let’s talk about each layer a bit more.

The Data Layer

A database, in this case Couchbase, will act as the data layer of your application. Why are we choosing
to use Couchbase as our NoSQL database, or for that matter, our database in general? I’ll brush in this soon,
but in short, we’re using NoSQL because our application will be RESTful and serve JSON data. We’re using
Couchbase because we want the freedom to use SQL queries or key-value (k-v) operations.

SQL and Key-Values in NoSQL?

With NoSQL document databases, each of your documents have a lookup key or id. When supplying the key in the
lookup, you get a value or in our case JSON data. If you’re new to databases this concept might not be too
difficult to grasp, but if you’re coming from a database like Oracle or MySQL it could sound like pure

In relational database management systems (RDBMS) like Oracle or SQL Server if you want to get data from the
database you can run SQL queries.

With Couchbase 4.0, you now have what is called N1QL which allows you to run SQL queries against your NoSQL
database while leaving you with the option to use key-value lookups as well. Best of both worlds by being
able to make the choice yourself.

Some Sample Documents

Being that this is a travel booking application, you are probably going to be working with airline
information, and airport information. Of course you will probably have plenty of other information, but
for the sake of this article, it doesn’t really matter.

Based on what we know we need to accomplish, the NoSQL documents for our data can look something like



Each of those JSON documents will probably contain plenty of other information in reality, but the slimmed down
versions above should be fine.

We now should have enough information about our data layer to start learning about the backend layer.

The Backend API Layer

The whole purpose behind the backend is to serve as a bridge between your data and the UI that every user
using your application sees on their screen. In this case, the backend would be Java.

The Java layer will make requests against the database, format the responses, and then return them back
to the end user for displaying. The end user making the requests to the Java layer will do so via endpoints
in the backend. Think of an endpoint as a different URL in your application, each responding with
different data.

The client-facing UI layer

The purpose behind the client-facing UI layer is to give the end user something pleasant to work with rather
than processing raw code. Someone visiting a travel website like Expedia may not have any developer
experience at all. The front-end layer will normally consist of a language like AngularJS, ReactJS, or

Developing the Application

We know that our development process is going to be split into parts. Primarily, a front-end and a
back-end. Instead of building the full application from scratch we’re going to talk about what is
necessary to accomplish each part.

Serving a RESTful API

Out of the box you’ll find that Java can’t accept and respond to HTTP requests. There are many options
for accomplishing this, but one option might be to use Spring Boot because you can quickly get an API
running. With Spring Boot, you might create API endpoints that look like this:

If the user hits www.yourapp.com/airline in their browser or front-end application, the
airlineid passed will be processed with some logic that you define and then some response
data is returned. The logic you define, might involve querying for data.

Querying for Data

Let’s say you have a few of each document type in your Couchbase database. By each document type I mean
airport and airline. Now let’s say your Java back-end received a
request from your front-end to get information about the United airliner. We have two
options for getting this information:

Getting an Airline with K-V Lookup

Below we’re assuming that each airline document is prefixed with the key name airline:: and
that the airlineid was passed from the front-end.

We’re doing a lookup based on that compound key and creating a JsonObject out of the result. At this point
we can craft some Java code to return the result back to the front-end.

Getting an Airline with N1QL

Just like with the k-v lookup, we’re assuming the document keys are compound and are prefixed with
airline::. We are also assuming the key id is passed from the front-end.

Above is a N1QL query which is very similar to what you’d find with SQL. Both options are valid for
obtaining information about the airline. However, in scenarios where you are querying data from different
document types (a join maybe), it may be more beneficial to use N1QL rather than lookups. The reasons

  1. Couchbase Server does all the heavy lifting rather than the back-end
  2. Less code in your back-end

Wrapping It Up

You’ve gotten a taste of what is necessary to serve HTTP endpoints in Java and how to query for data via
the Java back-end, but where does that leave us now?

You just need to add more endpoints to your Java API, each of which performing different queries or
lookups against Couchbase.


When designing a web application you’re going to have several layers that play together. Couchbase is always
a good choice because it is a JSON document database thus making APIs easy to craft. The Couchbase Java
SDK is great because you are left with plenty of simple options for querying data.

Although this wasn’t a thorough create an application from start to finish type of article, I recommend
you check out the tutorial I wrote regarding creating a travel


Posted by Nic Raboy, Developer Advocate, Couchbase

Nic Raboy is an advocate of modern web and mobile development technologies. He has experience in Java, JavaScript, Golang and a variety of frameworks such as Angular, NativeScript, and Apache Cordova. Nic writes about his development experiences related to making web and mobile development easier to understand.

Leave a reply