@gmmurray/mongodb-atlas-data-api

A client library for interacting with the Atlas Data API.

Prerequisites

This library requires the following dependencies:

• axios for making HTTP requests.

$ npm install axios

Table of Contents

• @gmmurray/mongodb-atlas-data-api
  • Prerequisites
  • Table of Contents
  • Getting Started
  • Installation
  • Usage
    • Creating the Client
    • Find One Document
    • Find Many Documents
    • Insert One Document
    • Insert Many Documents
    • Update One Document
    • Update Many Documents
    • Replace One Document
    • Delete One Document
    • Delete Many Documents
    • Aggregate Documents
  • API Reference
  • Credits

Getting Started

These instructions will help you get started with using the Atlas Data API Client in your project.

Installation

To install the library, run the following command:

$ npm install atlas-data-api-client

Alternatively, you can use Yarn:

$ yarn add atlas-data-api-client

Usage

In these examples we use a made up customer interface:

interface Customer {
  id: string;
  name: string;
  age: number;
}

Creating the Client

import AtlasDataApiClient, {
  AtlasDataApiClientOptions,
} from '@gmmurray/atlas-data-api-client';

const options: AtlasDataApiClientOptions = {
  apiKey: 'YOUR_API_KEY',
  dataApiUrlEndpoint: 'your-app-url-endpoint',
  defaultDataSource: 'your-default-data-source',
  defaultDatabase: 'your-default-database',
};

const apiClient = new AtlasDataApiClient(options);

Find One Document

const request: FindOneDocumentRequest<Customer> = {
  collection: 'your-collection',
  filter: { name: 'John Doe' },
};

const response: FindOneApiResponse<Customer> = await apiClient.findOneDocument(
  request,
);

console.log(response);

Find Many Documents

const request: FindManyDocumentsRequest<Customer> = {
  collection: 'your-collection',
  filter: { age: { $gte: 18 } },
  sort: { name: 1 },
  pageSize: 10,
  pageNumber: 1,
};

const response: FindManyApiResponse<Customer> = await apiClient.findDocuments(
  request,
);

console.log(response);

Insert One Document

const request: InsertOneDocumentRequest<Customer> = {
  collection: 'your-collection',
  document: { name: 'John Doe', age: 25 },
};

const response: InsertOneApiResponse = await apiClient.insertOneDocument(
  request,
);

console.log(response);

Insert Many Documents

const request: InsertManyDocumentsRequest<Customer> = {
  collection: 'your-collection',
  documents: [
    { name: 'John Doe', age: 25 },
    { name: 'Jane Smith', age: 30 },
  ],
};

const response: InsertManyApiResponse = await apiClient.insertManyDocuments(
  request,
);

console.log(response);

Update One Document

const request: UpdateOneDocumentRequest<Customer> = {
  collection: 'your-collection',
  filter: { id: '123' },
  update: { name: 'John Doe', age: 26 },
  upsert: true,
};

const response: UpdateOneApiResponse = await apiClient.updateOneDocument(
  request,
);

console.log(response);

Update Many Documents

const request: UpdateManyDocumentsRequest<Customer> = {
  collection: 'your-collection',
  filter: { age: { $gte: 18 } },
  update: { status: 'active' },
  upsert: true,
};

const response: UpdateManyApiResponse = await apiClient.updateManyDocuments(
  request,
);

console.log(response);

Replace One Document

const request: ReplaceOneDocumentRequest<Customer> = {
  collection: 'your-collection',
  filter: { id: '123' },
  replacement: { id: '123', name: 'John Doe', age: 27 },
  upsert: true,
};

const response: ReplaceOneApiResponse = await apiClient.replaceOneDocument(
  request,
);

console.log(response);

Delete One Document

const request: DeleteOneDocumentRequest<Customer> = {
  collection: 'your-collection',
  filter: { id: '123' },
};

const response: DeleteOneApiResponse = await apiClient.deleteOneDocument(
  request,
);

console.log(response);

Delete Many Documents

const request: DeleteManyDocumentsRequest<Customer> = {
  collection: 'your-collection',
  filter: { age: { $gte: 18 } },
};

const response: DeleteManyApiResponse = await apiClient.deleteManyDocuments(
  request,
);

console.log(response);

Aggregate Documents

const request: AggregateDocumentsRequest = {
  collection: 'your-collection',
  pipeline: [
    { $match: { age: { $gte: 18 } } },
    { $group: { _id: '$gender', count: { $sum: 1 } } },
  ],
};

const response: AggregateApiResponse = await apiClient.aggregateDocuments(
  request,
);

console.log(response);

API Reference

| Method | Description | | ------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | findOneDocument(request: FindOneDocumentRequest): Promise<FindOneApiResponse> | Finds a single document in the specified collection. | | findDocuments(request: FindManyDocumentsRequest): Promise<FindManyApiResponse> | Finds multiple documents in the specified collection. | | insertOneDocument(request: InsertOneDocumentRequest): Promise | Inserts a single document into the specified collection. | | insertManyDocuments(request: InsertManyDocumentsRequest): Promise | Inserts multiple documents into the specified collection. | | updateOneDocument(request: UpdateOneDocumentRequest): Promise | Updates a single document in the specified collection. | | updateManyDocuments(request: UpdateManyDocumentsRequest): Promise | Updates multiple documents in the specified collection. | | replaceOneDocument(request: ReplaceOneDocumentRequest): Promise | Replaces a single document in the specified collection. | | deleteOneDocument(request: DeleteOneDocumentRequest): Promise | Deletes a single document from the specified collection. | | deleteManyDocuments(request: DeleteManyDocumentsRequest): Promise | Deletes multiple documents from the specified collection. | | aggregateDocuments(request: AggregateDocumentsRequest): Promise | Performs an aggregation on the specified collection. |

For more details on each method and their request/response types, please refer to the source code documentation.

Credits

• Axios
• README template