website logo
⌘K
πŸ–οΈIntroduction to hyper cloud
🍎Getting Started
😍What's New
Legacy Get Migration Guide
Blueberry Migration Guide
πŸ’ͺWorkshops
Deno Workshops
NodeJS Workshops
⚑Quickstarts
NodeJS Quickstarts
πŸ”ŒAPI Reference (hyper cloud)
🍎Basics
⚑hyper connect
πŸ”‘JWT Auth
πŸ’ΎData API
🏎️Cache API
πŸ”ŽSearch API
πŸ—„οΈStorage API
πŸ€“Queue API
πŸ”“Sign In
⚑Applications
βš™οΈSettings
πŸ”‘App Keys
πŸ‘₯Teams
Switching Between Accounts
Application Services
Application Service Instances
Adding a Queue Service
Adding a Search Service
Subscriptions
πŸ€‘Upgrade
πŸ“•Terminology
Parameters
πŸ’³Billing
Payment and Pricing Terms
πŸ’ΌLegal
Terms of Service
Acceptable Use Policy
Privacy Policy
πŸ•ΆοΈHyper Vision
Docs powered byΒ archbeeΒ 
26min

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
ο»Ώ

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.
  • ο»Ώο»Ώ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
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
|
curl localhost:3001
ο»Ώ
  • If you see the following response in your terminal, then you are ready to code!
JSON
|
{"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 /
Node.js
|
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.
JS
|
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 πŸ¦•.

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

ο»Ώ
  • 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
|
export default async function (req, res) {
  const result = await hyper.data.add(req.body);
  return res.send(result);
}
ο»Ώ

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
|
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
|
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
|
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ο»Ώ

ο»Ώ

ο»Ώ

Updated 25 Apr 2022
Did this page help you?
Yes
No
UP NEXT
What's New
Docs powered byΒ archbeeΒ 
TABLE OF CONTENTS
Create a hyper application and data service
It's Free
Copy the app key's connection string
Code setup
A quick code tour
Create the HYPER environment variable
Add a document
Get a document
Next Steps