NodeJS

Before you get started!

This documentation assumes you have an active MeshyDB account. If you do not, please create a free account at https://meshydb.com.

Once you verify your account you will need to gather your Account Name and Public Key.

Identify Account Name

Your Account Name can be found under the Account page. See image below:

Account Name under Account

Identify Public Key

Your Public Key can be found under the Clients page under your default tenant. See image below:

Public Key under Clients default tenant

In the following we will assume no other configuration has been made to your account or tenants so we can just begin!

Install SDK

The supporting SDK is open source and you are able to use a browser or NodeJS application.

Let’s install the MeshyDB.SDK NPM package with the following command:

npm install @meshydb/sdk

Initialize

The client is used to establish a connection to the API. You will need to provide your Account Name and Public Key from your account and client.

var client = MeshyClient.initialize(accountName, publicKey);

Parameters

accountName : string, required
Indicates which account you are connecting to.
publicKey : string, required
Public identifier of connecting service.

Register Anonymous User

Anonymous users are great for associating data to people or devices without having them go through any type of user registration.

The example below shows verifying a username is available and registering an anonymous user if the username does not exist.

var username = "mctesterton";

var userExists = await client.checkUserExist(username);

if (!userExists.exists) {
   await client.registerAnonymousUser(username);
}

Parameters

username : string
Unique identifier for user or device. If it is not provided a username will be automatically generated.

Responses

201 : Created
  • New user has been registered and is now available for use.

Example Result

{
   "id": "5c78cc81dd870827a8e7b6c4",
   "username": "mctesterton",
   "firstName": null,
   "lastName": null,
   "verified": false,
   "isActive": true,
   "phoneNumber": null,
   "emailAddress": null,
   "roles": [],
   "securityQuestions": [],
   "anonymous": true
}
400 : Bad request
  • Username is a required field.
  • Anonymous registration is not enabled.
  • Username must be unique.
429 : Too many request
  • You have have either hit your API or Database limit. Please review your account.

Login

All data interaction must be done on behalf of a user. This is done to ensure proper authorized access of your data.

The example below shows logging in an anonymous user.

var connection = await client.loginAnonymously(username);

Parameters

username : string, required
Unique identifier for user or device.

Responses

200 : OK
  • Generates new credentials for authorized user.

Example Result

{
  "access_token": "ey...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "ab23cd3343e9328g"
}
400 : Bad request
  • Token is invalid.
  • Client id is invalid.
  • Grant type is invalid.
  • User is no longer active.
  • Invalid Scope.
  • Username is invalid.
  • Password is invalid.
429 : Too many request
  • You have have either hit your API or Database limit. Please review your account.

Once we login we can access our connection through a static member.

connection = MeshyClient.currentConnection;

Retrieving Self

When a user is created they have some profile information that helps identify them. We can use this information to link their id back to data that has been created.

The example below shows retrieving information of the user.

var user = await connection.usersService.getSelf();

Parameters

No parameters provided.

Responses

200 : OK
  • Retrieves information about the authorized user.

Example Result

{
   "id": "5c78cc81dd870827a8e7b6c4",
   "username": "mctesterton",
   "firstName": null,
   "lastName": null,
   "verified": false,
   "isActive": true,
   "phoneNumber": null,
   "emailAddress": null,
   "roles": [],
   "securityQuestions": [],
   "anonymous": true
}
401 : Unauthorized
  • User is not authorized to make call.
429 : Too many request
  • You have have either hit your API or Database limit. Please review your account.

Create data

Now that a user connection is established you can begin making API requests.

The example below shows committing a new person.

var model = {
               _id: undefined,
               firstName: "Bob",
               lastName: "Bobson",
               userId: user.id
            };

var meshName = "person";

model = await connection.meshesService.create(meshName, model);

Parameters

meshName : string, required
Identifies which mesh collection to manage.
model : object, required
Represents a person in this example.

Responses

201 : Created
  • Result of newly created mesh data.

Example Result

{
   "_id":"5d438ff23b0b7dd957a765ce",
   "firstName": "Bob",
   "lastName": "Bobson",
   "userId": "5c78cc81dd870827a8e7b6c4"
}
400 : Bad request
  • Mesh name is invalid and must be alpha characters only.
  • Mesh property cannot begin with ‘$’ or contain ‘.’.
401 : Unauthorized
  • User is not authorized to make call.
429 : Too many request
  • You have have either hit your API or Database limit. Please review your account.

Update data

The API allows you to make updates to specific Mesh Data by targeting the id.

The SDK makes this even simpler since the id can be derived from the object itself along with all it’s modifications.

The example below shows modifying the first name and committing those changes to the API.

model.firstName = "Robert";

model = await connection.meshesService.update(meshName, model);

Parameters

meshName : string, required
Identifies which mesh collection to manage.
model : object, required
Represents a person in this example.

Responses

200 : OK
  • Result of updated mesh data.

Example Result

{
   "_id":"5d438ff23b0b7dd957a765ce",
   "firstName": "Robert",
   "lastName": "Bobson",
   "userId": "5c78cc81dd870827a8e7b6c4"
}
400 : Bad request
  • Mesh name is invalid and must be alpha characters only.
  • Mesh property cannot begin with ‘$’ or contain ‘.’.
401 : Unauthorized
  • User is not authorized to make call.
429 : Too many request
  • You have have either hit your API or Database limit. Please review your account.

Search data

The API allows you to search a mesh collection using a MongoDB expression.

The example below shows searching based where the first name starts with Rob.

var filter = { 'firstName': { "$regex": "^Rob" } };

var pagedPersonResult = await connection.meshesService
                                        .search(meshName, { filter: filter });

Parameters

meshName : string, required
Identifies which mesh collection to manage.
filter : object
Criteria provided in a MongoDB expression to limit results.

Responses

200 : OK
  • Mesh data found with given search criteria.

Example Result

{
   "page": 1,
   "pageSize": 25,
   "results":  [{
                  "_id":"5d438ff23b0b7dd957a765ce",
                  "firstName": "Robert",
                  "lastName": "Bobson",
                  "userId": "5c78cc81dd870827a8e7b6c4"
               }],
   "totalRecords": 1
}
400 : Bad request
  • Mesh name is invalid and must be alpha characters only.
  • Filter is in an invalid format. It must be in a valid Mongo DB format.
  • Order by is in an invalid format. It must be in a valid Mongo DB format.
401 : Unauthorized
  • User is not authorized to make call.
429 : Too many request
  • You have have either hit your API or Database limit. Please review your account.

Delete data

The API allows you to delete a specific Mesh Data by targeting the id.

The example below shows deleting the data from the API by providing the object.

Deleted data is not able to be recovered. If you anticipate the need to recover this data please implementing a Soft Delete.

var id = model._id;

await connection.meshesService.delete(meshName, id);

Parameters

meshName : string, required
Identifies which mesh collection to manage.
id : string, required
Identifier of record that must be deleted.

Responses

204 : No Content
  • Mesh has been deleted successfully.
400 : Bad request
  • Mesh name is invalid and must be alpha characters only.
401 : Unauthorized
  • User is not authorized to make call.
404 : Not Found
  • Mesh data was not found.
429 : Too many request
  • You have have either hit your API or Database limit. Please review your account.

Sign out

The MeshyDB SDK manages a single connection to the API.

The Meshy SDK handles token management, this includes refresh tokens used to maintain a user’s connection.

As a result it is recommended to implement Sign Out to ensure the current user is logged out and all refresh tokens are revoked.

The example below shows signing out of the currently established connection.

await connection.signout();

Parameters

No parameters provided. The connection is aware of who needs to be signed out.

Responses

200 : OK
  • Identifies successful logout.
400 : Bad request
  • Invalid client id.
  • Token is missing.
  • Unsupported Token type.
429 : Too many request
  • You have have either hit your API or Database limit. Please review your account.

Not seeing something you need? Feel free to give us a chat or contact us at support@meshydb.com.