Find (and fork) the full project repository on my Github.

Ifyou’re like me, you probably like movies. Everyone likes movies. The problem is picking the right one to watch, or even finding suggestions or data about who acted a movie that interests you, or when it was released. Most of the time you have to go to Google and spend about 5 minutes looking for this information, or even more when looking for movie suggestions.

Today, we’re going to build a simple terminal app that can save us those five minutes, using an API that can help us quickly get movie data and suggestions. You can get the app up and running in around ten minutes, and you can even use it to get access to those cool movie posters we all love, without visiting Google Images, all presented in a nice little table on your terminal.

Getting Started- The Online Movie Database API

To start, you need a Rapid API account to get access to the freemium Online Movie Database API, which we will be using to search for movies in this project. Signing up to Rapid API is free, and there are millions of APIs you can play with. You can sign up for Rapid API here, then subscribe to the Online Movie Database API using this link.

You’ll also need a machine that has a Java Development Kit installed. You’ll also need an IDE, I will be using Netbeans, other popular options are VS Code and Eclipse. Finally, you’ll need Apache Maven (or Gradle) installed on your machine, so that we can manage our dependencies. I will use Maven.

Let’s Look at How The API Works

Once you have subscribed to the API, you get a playground from where you can test an API endpoint to see how it works. We will be testing the GET auto-complete end point to build out app. Here is a general overview of how it looks like:

Playground View of the Online Movie Database API

From the presentation, we know that all we need in order to use the API endpoint (and to build our app) is an API key, and a query string. The query string is the movie you’re searching for. Let’s make an example request using the provided string ‘game of thr’- Game of Thrones. Note that this is how the code for the request looks like:

Understanding the Playground Code

Testing the API Endpoint With an Example Query String

From the language drop-down, select Java as your testing language, and choose Unirest as your HTTP client. When we click the ‘Test Endpoint’ button, we get back a JSON response. JSON is a common format by which many apps (using mostly RESTfull APIs) communicate. JSON content is objects made of key-value pairs.

In Java, it’s good to map the JSON to an object (using the keys as the object’s instance variables), and Unirest makes that easy, so that you can access the various parts of it in your project. But first, let’s understand the JSON being sent back by the API.

Understanding the Response JSON

Sample Response JSON

With JSON, we have objects/ resources and collection of objects, that’s it. An object is denoted by ‘{}’ while a collection is denoted by ‘[]’. These may be nested in each other.

From our response JSON, we have an anonymous (meaning there is no name before the opening ‘{‘ ) outer object, which we can call MovieResponseObject. Inside this object, we have a collection of movie objects (which are suggested based on your query). The collection has been named ‘d’, and acts like an array with it’s elements starting at index zero.

The element in this case is a single movie suggestion, with data that makes it up. This collection has 8 similar movie objects. But look closer, the movie object has an object named ‘i’. This is actually an Image object representing the poster for that movie object. Let’s expand it and see what it looks like inside:

Analysis of the Image Object

Every poster is made up of an image height, an imageURL to locate it on the net and an image width. We may need the imageURL for our app. Further down our movie object, we see a nested collection named ‘v’. This is a collection of videos related to that movie (like movie trailer). Let’s also expand it and see what the collection is made of:

Analyzing the Related Videos Collection

Although the video objects are not relevant to us, it is worth noting that similar to the parent movie object, every video has an image (a thumbnail) related to it, with the same width, height and imageUrl parameters. Now we understand the response JSON. Let’s get to the juicy part- coding.

Creating the Maven Project

From whatever IDE you’re using, create a Maven project with these parameters: (Use the maven-simple-archetype) plugin.

Setting up The Maven Project

Once the project is created, you should see a parent folder named SimpleIMDbApp in your IDE. Expanding the app, this is the structure we see:

Project Structure

You can delete the ‘Test’ folder as we won’t be writing any JUnit5 tests in this article.

Editing the POM.XML File- Adding Dependencies

Open your POM file, and edit your dependencies and properties section to look like this:

Editing POM.XML

Read the comments to know what each dependency does. Note that you should use the JDK version installed on your machine as the argument for the ‘<maven.compiler.target>’ section. For example, I am using JDK 17 LTS.

About Picocli- Making Terminal Apps with Java

Picocli is a simple framework (or library?) for building terminal applications using Java, Kotlin or Groovy. We won’t use it as much in this article, but it simply allows as to design and package out app as a terminal app, so that our users interact with it like with all other terminal apps- using commands.

Creating the Necessary Classes

Now that we know how our JSON looks like, we will create a class file that matches the JSON, and use Unirest to map the JSON to that class. We will also modify the App.java file to be our main entry point.

So now, add the MovieResponseObject.java file to your project. This is how your ‘after’ project structure should look like:

Updated Project Structure

Taking in the User Query- Modifying App.java

Remember from the playground we saw that all you need to use the API is a query string and your API key. Let’s handle the query string part. We will use picocli annotations to implement a way for the user to both call the app and provide a query string right from the terminal (we will ‘mimic’ the terminal in this tutorial though).

So modify your App.java file to look like this: (App.java is the entry point into our application)

Modifying the App.java File

When we run our app (the App.java file) the main() method will run. It builds a new command for us and executes it based on the values passed to the execute() method.Our class implements the Runnable interface, so we have to implement the run() method.

How App.java Works- How the Application Runs

When the main() method has been initiated, it makes a call to run(), passing in the arguments given to execute(), except the ‘-q’ string. This string is a marker denoting that whatever we’re passing in after it is the search query (line 9), and is created by marking a variable(in this case ‘query’) with the ‘@Option’ annotation.

So now we can capture any query input (we’ll use the example of Game of Thrones), but how do we process it?

Making the API Call- Unirest, Editing the GetMovie.java File

After getting the user query input, we have to pass it to Unirest to make the API GET request for us. This logic is placed in the GetMovie.java file, so you have to edit it to look like this:

Editing GetMovie.java to Make our API Calls

The search query is passed to Unirest as a part of the URL (line 13).

Because what we get back from the API endpoint is a JSON object as a response, we can use Unirest to map this response to an actual POJO (Plain Old Java Object) as on line 17. The handleJSON() method is used to build a table using the data contained in the POJO, and the table is made pretty, and presented to the user using the ‘Freva ASCII Tables’ dependency that we imported earlier.

But where is this POJO coming from? We need to build that too.

Last Touch- Creating The Class to Map The JSON To

Remember that we decided to name the parent anonymous object in the JSON as ‘MoviesResultObject’. We need to create a class that matches this (hence the ‘MoviesResultObject.java’ file), using the keys in the JSON as instance variables.

It is this class that Unirest will map the JSON in the response to, hence forming the POJO for us, that we can then use to build the table to view our results in. So let’s build the class. It should look like this:

The Class To Map The JSON To

Notice that in this class, we have only used the necessary components of the JSON response, and utilized those to build the table. Now we’re done with the code. Let’s take it for a test run.

Testing the App Using Game of Thrones- Running App.java

When you go back to App.java and run it as it is (press SHIFT + F6), passing ‘game of thrones’ as the argument to the execute() method, here is what you’ll see on your terminal output:

Example Output

And viola! You have movie metadata, a couple of suggestions to watch and a link to the movie poster to easily download to your local storage. How easy was that? Try changing ‘game of thrones’ to ‘avengers’ and re-run App.java and see the results.

Conclusion

In this article we’ve built a simple terminal app using the Online Movie Database API to search for movies, their data and even get movie suggestions, all from your terminal. We didn’t go that far though.

To see how cool the app can get (including auto-downloading the posters for you), check out the IMDbOnTerminal repository on Github. It’s free to use, install and edit the source code to suit your needs.

More from Bikathi Martin