40min

Getting Started

Welcome to hyper ⚡️. Let's create a simple ExpressJS REST API that leverages the hyper connect SDK to add and retrieve documents to the hyper data service.

As you complete this tutorial you will learn how to:

  • Create a hyper application and data service using the developer dashboard.
  • Use an app key's connection string to set up a HYPER environment variable
  • Securely connect to hyper using the hyper connect SDK.
  • Create a document and retrieve a document to/from the data service

Here's a high-level sequence diagram of what we will build:

Our API provides a consistent shape across all our services, making it easy to learn. For example, adding something to a service feels the same across different service types:

  • hyper.data.add({...})
  • hyper.cache.add(key, value, [ttl])
  • hyper.search.add(key, {...})

Create a hyper application and data service

A hyper application represents an application within hyper cloud. Each hyper application is owned by either a user account or a team. A hyper application contains key pairs used to access its application services, such as Data, Storage, Cache, Queue, and Search. Creating a hyper app provides the primary mechanism for controlling which of your client apps can access the resources protected by the hyper cloud.

"hyper enables us to spend time on what matters. By providing a well-defined interface for things like data persistence, caching, and search, hyper allows us to avoid bike-shedding and reinventing logic that is common across the majority of our applications. Instead, we can spend our time working on the details that make each project unique and keep our focus on providing value to the customer." - Travis Nesland, Senior Lead Developer at Sovereign, co.

It's Free

You get 3 hyper applications as part of your free Starter plan. A Pro plan allows up to 10 hyper applications and a Business plan allows up to 20. For more information see Pricing.

Now, let's create a hyper application.

  • Sign in to the hyper developer dashboard with your GitHub account.
  • Create a hyper application.
    • We create a unique app name for you. You can change the app name if you prefer.
    • Select the data hyper service on the Add hyper application screen. This will create a data service named "default".
Creating a hyper app and data service
Creating a hyper app and data service

Copy the app key's connection string

Once created, you will see the new app in your list of applications.

  • Select the app in the list of applications to open the app page:
Applications page
Applications page

Selecting a hyper app from the Applications page will display the application and a series of tabs. The Keys tab contains your App Keys.

An app key consists of a Key, Secret, and associated Connection String. An app key allows hyper to uniquely identify your app. Our ExpressJS API will need an app key when negotiating access to the resources protected by hyper cloud. A hyper cloud connection string consists of a key, secret, hyper cloud server, and hyper app name:

cloud://<key>:<secret>@cloud.hyper.io/<hyper application name>

App page, Keys tab, and connection string
App page, Keys tab, and connection string

Use the copy button to copy the connection string to your clipboard. The real secret will be copied even if it is redacted in the user interface.

In a future step, we will provide the connection string value to the hyper connect SDK.

Code setup

We've provided a hyper-getting-started-guide-express repository on GitHub. You can clone the repo from GitHub or code in the cloud by 🚀 Launching a Workspace 🚀 with Gitpod. 

Once you have the code open within your IDE, let's install dependencies

  • Open a terminal and ensure you are in the project directory: hyper-getting-started-guide-express.
  • Ensure you are on the main git branch.
  • Run npm install to install the project's dependencies.
  • Run npm start to run the API server locally on port 3001.
  • Open a separate terminal and run the following curl command:
Curl
|
  • If you see the following response in your terminal, then you are ready to code!
JSON
|

A quick code tour

Open the server.js file which defines the ExpressJS API. Here you will find three endpoints:

  1. Retrieve a document - GET /docs
  2. Add a document - POST /docs
  3. Retrieve the welcome message GET /
Node.js
|

Our goal is to complete the callback functions for the GET /docs and POST /docs endpoints.

Create the HYPER environment variable

  • Open the developer portal, locate your new hyper app, and copy the hyper app's connection string to the clipboard.
  • In the editor, create a .env file at the root of your project.
  • Within the .env file, create a HYPER environment variable and paste the connection string as the value.
JS
|

Add a document

Open api/add-doc-to-data-svc.js. This file provides the callback function for the POST /docs endpoint. Add the following code:

  • import and call the connect function from hyper-connect using the HYPER environment variable.

hyper-connect is the client access library for hyper, built for Javascript and Typescript. hyper-connect uses Javascript Promises and the fetch specification, as a base layer for interacting with hyper's REST API. You will find this approach with autocomplete, creates intuitive usability. hyper-connect supports both NodeJS and Deno 🦕.

Node.js
|
  • Call hyper.data.add to add the document to the data service.

For a complete listing of hyper-connect methods for the data service, see Data Service Methods.

Node.js
|

Since hyper-connect is promised-based, composition between different hyper services is possible. See our video workshops and quickstarts for examples of composing hyper services.

Get a document

In your editor, open the api/get-doc-from-data-svc.js. This file provides the callback function for the GET/docs/:id endpoint. It will retrieve a document given the document id provided in the path. Add the following code:

Node.js
|

At this point, we have created two API endpoints to handle adding and retrieving a JSON document to and from a data service within your hyper app.

Let's add some documents:

  • Ensure the API is running locally on port 3001
Curl
|

Now let's retrieve the documents:

Curl
|

Next Steps







Updated 25 Apr 2022
Did this page help?
Yes
No