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:

sequenceDiagram
    participant App as Client App
    participant API as ExpressJS REST 
    participant addDoc
    participant getDoc
    participant H as hyper connect
    participant HD as hyper Data Service
    
    Note over App,API: Add Doc
    App-)API: POST /docs
    API->>addDoc: JSON document
    addDoc->>H: connect(hyper app connection string)
    H-->>addDoc: hyper object
    addDoc-)H: hyper.data.add(JSON document)
    Note over H,HD: hyper connect handles auth
    H-)HD: HTTP POST to data service
    HD--)H: success response {"ok":true,"id":"1"}
    H--)addDoc: success response {"ok":true,"id":"1"}
    addDoc--)API: success response {"ok":true,"id":"1"}
    API--)App: success response {"ok":true,"id":"1"}

    Note over App,API: Get Doc
    App-)API: GET /docs/1
    API->>getDoc: document id (1)
    getDoc->>H: connect(hyper app connection string)
    H-->>getDoc: hyper object
    getDoc-)H: hyper.data.get(document id)
    Note over H,HD: hyper connect handles auth
    H-)HD: HTTP GET to data service
    HD--)H: doc {"_id":"1","name":"Mittens",...}
    H--)getDoc: doc
    getDoc--)API: doc
    API--)App: doc

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.

Now, let's create a hyper application.

• Sign in to the hyper developer dashboard with your GitHub account.
• 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".

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



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



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.

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 localhost:3001

• If you see the following response in your terminal, then you are ready to code!

{"name":"Welcome to the Getting Started Guide Express API","ok":true}

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 /

app.post("/docs", addDoc);
app.get("/docs/:id", getDoc);

app.get("/", function (req, res) {
  res.send({ name: "Welcome to the Getting Started Guide Express API", ok: true });
});

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.

HYPER=<connection string goes here>

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 🦕.

import { connect } from "hyper-connect";
const hyper = connect(process.env.HYPER);

• Call hyper.data.add to add the document to the data service.

export default async function (req, res) {
  const result = await hyper.data.add(req.body);
  return res.send(result);
}

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:

import { connect } from "hyper-connect";
const hyper = connect(process.env.HYPER);

export default async function (req, res) {
  console.log("getting doc: ", req.params.id);
  const doc = await hyper.data.get(req.params.id);
  return res.send(doc);
}

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 -X POST localhost:3001/docs \
-H 'content-type: application/json' \
-d '{"_id": "1", "name": "Mittens", "type": "cat", "breed": "tabby" }'

curl -X POST localhost:3001/docs \
-H 'content-type: application/json' \
-d '{"_id": "2", "name": "Trixie", "type": "cat", "breed": "siamese" }'

curl -X POST localhost:3001/docs \
-H 'content-type: application/json' \
-d '{"_id": "3", "name": "Wilma", "type": "cat", "breed": "Maine Coon" }'

Now let's retrieve the documents:

curl localhost:3001/docs/1 | npx prettyjson
curl localhost:3001/docs/2 | npx prettyjson
curl localhost:3001/docs/3 | npx prettyjson

Next Steps

• New to document databases? Check out our blog post on document database design.
• Since hyper connect is promised-based, you can compose calls to different services. Our video workshops and code quickstarts provide some examples.
• Checkout out our Pricing options.
• Read our Blog
• Join the community
• Follow us on Twitter and Linked-In