Getting Started with the Harper REST API

The Harper platform streamlines many parts of development. The part we will focus on today is highlighting how the Harper platform can streamline REST APIs and the integration of them into an application. In this tutorial we will integrate Harper into a todo web app.

Overview

In this article we will:

1. Install & setup Harper in our local developer environment
2. Configure our existing application with Harper
3. Integrate and test the REST API endpoints into our application

Install and Setup Harper

To install Harper locally, open you terminal and enter:

npm install -g harperdb

Once the install is successful run this command:

harper

The time running harper you will be prompted/asked to setup your:

• Destination - Where Harper will be on your machine
• Username - You will use to login into Harper Studio on your local machine
• Password - You will use to login into Harper Studio on your local machine
• Configuration - Option to configure Harper

Once you have gone through the first time installation and setup you will have successfully installed Harper on your machine!

To access Harper Studio while running Harper navigate to:

http://localhost:9925/

Use the your username and password created during your setup to sign in.

When you sign into Harper Studio, you immediately navigate to the "applications" page, where you're able to manage applications. The other navigation items are:

• Databases - Where you can manage databases, tables, and their data
• APIs - Where you can view and test the list of api endpoints generated from the schema.graphql file(s)
• Status - A page detailing the status/metrics of the system hosting Harper
• Logs - A page for viewing the logs of the current Harper instance(or cluster depending upon your configuration)
• Config - Where an individual can add/remove/modify roles & users for this specific Harper instance and/or cluster.

Next let's stop running Harper and in the next section we will go into Applications and Databases during the process of setting up and configuring our application.

Application Setup

Before we can configure our todo app we need to clone our todo app.

git clone https://github.com/HarperFast/harper-todo-example

After we cloned the Harper Todo Example:

1. Open harper-todo-example -> start/ folder in your preferred I.D.E./Text-Editor
2. Open the terminal and run npm install
3. Run npm run dev
4. Navigate to <http://localhost:5173/>

Our application runs but two problems are apparent:

• We need to configure our application to run inside Harper
• We need to leverage Harper for the CRUD functionality of the app

Configuring our Application for Harper

For configuring our Todo application to run inside Harper we:

1. Install the harper vite plugin

npm install -D @harperfast/vite-plugin

2. Open our config.yaml and paste the plugin into it under line 20:

# Add @harperfast/vite-plugin here
'@harperfast/vite-plugin':
 package: '@harperfast/vite-plugin'

3. Open our package.json and replace the dev script with:

"dev": "harper run .",

When we stop our application and restart it with npm run dev, we can navigate to localhost:9926 and see our application working inside Harper.

What exactly did we do?

• We installed the Harper Vite plugin which enables our application to run inside Harper with little to no issues
• We opened our config.yaml, which is the way for us to configure our application that is running in Harper, and pasted our plugin we installed.
• We replaced vite dev with harper run . so our application can leverage the plugin to run inside Harper.

Configuring our application to run inside of Harper allows for us to leverage the In-Memory Cache, seamlessly integrated database, API Endpoint auto-generation, and more all while remaining with low-latency.

Creating our Table and Attributes

Harper uses a schema first approach to creating tables and attributes for applications. Essentially, we will create our table and attributes inside a schema file.

Open your schema.graphql and paste this:

type TodoList @table @export {
id: ID @primaryKey
status: String @index
description: String
}

In this snippet we:

• Created our type TodoList
• Included @table to define the type we created is the table name. Harper will create the table.
• Included @export telling Harper to auto-generate REST endpoints to interface with this table via our application
• Defined our attribute name, types, and directives for each record in our created table.

In your browser, navigate to http://localhost:9925> -> Databases -> TodoList

You will see your table and the attributes we defined within the schema!

 Aside:

• By default if there is no database defined, Harper will create a database with the default name data.
• When you make changes to a schema you will have restart harper to have those changes reflected (stoping and running npm run dev in your application will achieve this).

Adding a Record

For testing purposes let's add a new record

1. Click the "+ Add New Record(s)" button
2. Replace the current object with this:

{
 "status": "active",
 "description": "finish todo app"
}

3. Click "Save Changes"

We've now successfully added our first record to our TodoList table!

APIs

Navigate to the "APIs" page in Harper Studio.

When we defined the @export directive on our table Harper automatically generated  REST API endpoints and it's rendered using Swagger UI so we can interacting with the TodoList table from the browser via REST endpoints and test the rest endpoints as well.

Integrate our REST API Endpoints

In Harper to access and interact with our table and data by default Harper uses port 9926 for both the application http server port. To access our application in harper we go to <http://localhost:9926/> but to access the table we exported in we can navigate in our browser to <http://localhost:9925/TodoList/> . We will see the list of records in our Table.

Fetch Todos

Now that we have our REST API endpoints for the TodoList table, let's go inside our application and connect these API endpoints to the Todo application. In your application open src/main.ts.

Go to fetchTodos():
Here is where we need to fetch our TodoList table data:

// TODO: API Call to fetch todos.
todos = await fetch(`/TodoList/`).then(res => res.json());

Here, we make a call to the TodoList table and it returns the records from the table. If we navigate to our application on <http://localhost:9926/> , we will see the record we created earlier rendered in our todo application!

Change Todo Status

We now render a list of todos but it would be great to alter the completion status of each one. In Harper we're able to do this by adding the id of the selected todo item at the end of the url /<TableName>/<record-id>. We are also updating a record so we will be using PUT as our HTTP method. The content we are sending to our backend is JSON so our content type is application/json
Go to changeTodoStatus():

‍

// TODO: API Call to change the todo status.
await fetch(`/TodoList/${id}`, {
 method: 'PUT',
 headers: {
   'Content-Type': 'application/json',
 },
 body: JSON.stringify({
   // More code......
 }),
}).then(res => res.json());

Inside our body we need to:

• Pass the existing description into the body.
• Find what the current status of our record and toggle it to the latter.

// TODO: API Call to change the todo status.
await fetch(`/TodoList/${id}`, {
 method: 'PUT', // We're updating a record
 headers: {
   'Content-Type': 'application/json',
 },
 body: JSON.stringify({
   description: todos.find(todo => todo.id === id)?.description,
   status: todos.find(todo => todo.id === id)?.status === "active" ? "completed" : "active",
 }),
}).then(res => res.json());

Whenever we change to todo status via the checkbox it will make this call to Harper and update our table with the changed todo status.

Update Todo Description

Next we need to have a way to edit and update our todo items. Our fetch call will be similar to what we created above changeTodoStatus().

However, in this body we need to:

• Update the old description with the new one
• Pass the existing todo status

Go to updateTodoDescription():

await fetch(`/TodoList/${id}`, {
 method: 'PUT', // We're updating a record
 headers: {
   'Content-Type': 'application/json',
 },
 body: JSON.stringify({
description: newText,
status: todos.find(todo => todo.id === id)?.status,
 }),
})

Add Todo

In our application we currently have a form but no way to send the todos we've added to our table. In the previous 2 fetch calls where we update the description and status, we acquire the todo we wanted to modify by specifying the id in the api call to the TodoList table. Send there is no id specified for our new todo, we call the TodoList table without an id and pass the description with our default status "active" into the body.

Go to addTodo():

await fetch(`/TodoList/`, {
 method: 'POST',
 headers: {
'Content-Type': 'application/json',
 },
 body: JSON.stringify({
description: todoText,
status: "active",
 }),
}).then(res => res.json());

Delete Todo

Lastly, we have to implement the ability to DELETE a task. In order to do this we pass the id into the fetch url and designate the method as DELETE to specify we are deleting this todo item.

Go to deleteTodo():

// TODO: API Call to delete the todo.
await fetch(`/TodoList/${id}`, {
 method: 'DELETE',
 headers: {
'Content-Type': 'application/json',
 },
}).then(res => res.json());

Conclusion

We have now successfully built a full-stack todo application and streamlining the development with Harper. In this tutorial we leveraged Harper's:

• GraphQL Schema for table, attribute, and REST API generation.
• Development on the Harper platform locally for minimal setup in comparison to conventional full-stack application development.
• Streamlined deployment locally as well which we can replicate when we deploy on Harper Fabric, our cloud platform for Harper.

To build more with Harper visit https://www.harper.fast/

‍