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.
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.
- ο»Ώο»ΏApplications.
- 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".

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:

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>

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:
- If you see the following response in your terminal, then you are ready to code!
A quick code tour
Open the server.js file which defines the ExpressJS API. Here you will find three endpoints:
- Retrieve a document - GET /docs
- Add a document - POST /docs
- Retrieve the welcome message GET /
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.
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 π¦.
- 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.
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:
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
Now let's retrieve the documents:
Next Steps
- Since hyper connect is promised-based, you can compose calls to different services. Our video workshops and code quickstarts provide some examples.
ο»Ώ
ο»Ώ
