@aims-api/aims-node

AIMS Node

A Node.js library written in TypeScript to integrate the AIMS API.
You MAY USE this library on the client as well as on the server side.

Reach for more information at aimsapi.com

Report a Bug - Ask a Question

Table of Contents

• Report a Bug
• Getting Started
  • Authentication
  • Example with Next.js
• Usage
  • TypeScript support
  • Routes
  • Response Structure
• Development
  • Naming conventions
• License

---

Getting Started

To work with the package you need to have npm (or other package manager) installed. Library supports Node.js version 18 and above, and can be used in a client codebase.

npm install @aims-api/aims-node

# or

pnpm add @aims-api/aims-node

Authentication

In order to use the library you need to obtain an API key. You can get a demo key by contacting us at [e-mail].

Example with Next.js

TypeScript

// pages/api/searchByText.ts

import { NextApiRequest, NextApiResponse } from 'next'
import { Client as AIMSClient } from '@aims-api/aims-node'

const handler = async (req: NextApiRequest, res: NextApiResponse) => {
  if (req.method === 'POST') {
    try {
      const { text, filter } = req.body
      const aims = new AIMSClient({
        authorization: 'YOUR_API_KEY',
      })
      const response = await aims.endpoints.query.byText({ text, detailed: true, filter })
      return res.status(200).send(response)
    } catch (error) {
      return res.status(error.status).json(error.json)
    }
  }
  return res.status(400).json('Method not allowed')
}

export default handler

JavaScript

// pages/api/searchByText.js

import { Client as AIMSClient } from '@aims-api/aims-node'

const handler = async (req, res) => {
  if (req.method === 'POST') {
    try {
      const { text, filter } = req.body
      const aims = new AIMSClient({
        authorization: 'YOUR_API_KEY',
      })
      const response = await aims.endpoints.query.byText({
        text,
        detailed: true,
        filter,
      })
      return res.status(200).send(response)
    } catch (error) {
      return res.status(error.status).json(error.json)
    }
  }
  return res.status(400).json('Method not allowed')
}

export default handler

Usage

It is common to make a proxy request from client app to the server in order to hide foreign URL.

When you create a client instance in your codebase, you can then easily access all the existing endpoints via IDE autocomplete, as well as the required and optional parameters.

TypeScript support

The library uses Zod for response validation and type generation. Some of the types, Zod schemas and enums are publicly exported and can be accessed from @aims-api/aims-node/models.

In contrast to @aims-api/aims-node, any import from @aims-api/aims-node/models could be used in both browser and node environment, if needed.

Please note that the models may be subject to change before version 1.0.0 of @aims-api/aims-node is released.

Example:

import type { SearchResponse } from '@aims-api/aims-node/models'

Routes

The library provides a set of endpoints that can be found in src/client/index.ts file by the endpoints property on line #95.

List of all API endpoints could be found in AIMS API Documentation under Endpoints section, AIMS queries.

Response Structure

Both network errors and response structure errors are handled within a library, so the response is always a valid JavaScript Object in the following structure:

// successful request
{
  success: true
  data: any
}

// failed request
{
  success: false
  error: AxiosError | ZodError
}

Development

• Types should be inferred from Zod schemas, this way we are able to create valid checked responses and be generally flexible about the types. Zod schemas should be exported along with the types.

Naming conventions

• zod schemas are suffixed with *Schema and the name is in camelCase (e.g. collectionSchema). Interfaces derived from these schemas do not have the suffix and are in PascalCase (e.g. Collection).
• detailed objects use detailed* prefix (e.g. DetailedCollection or detailedCollectionSchema). This convention was adopted to correspond with requests with detailed: true argument.
• endpoints should export their *Request and *Response types (e.g. SimilarSearchResponse). For other than getter responses, the type should be provided (e.g. CreateSnapshotRequest or DeleteCollectionRequest). Note: These types represent payloads of the responses or requests, but are not in fact exported with the wrapping Response<T>. The complete request type would be e.g. type EndpointResponse = Response<CreateSnapshotResponse>.
• arrays of objects use *List* member (e.g. CollectionList or collectionListSchema), using plural form is deprecated (one exception being SimilarCollections)

License

See LICENSE for more information.