Getting Started

26min
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
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
﻿
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. 
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
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}
{"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: 
Retrieve a document - GET /docs
Add a document - POST /docs 
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 });
});
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>
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);

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);
}
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);
}

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" }'

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
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?
Introduction to hyper cloud
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