@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 - Request a Feature - Ask a Question

Table of Contents

• Getting Started
  • Authentication
  • Next.js example
• Usage
  • Routes
  • Response Structure
• 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

Authentication

In order to use the lirbary 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

Library uses Zod for response validation, therefore you can use the types that are provided in every endpoint file.

Example

import { type SearchResponse } from '@aims-api/aims-node/dist/endpoints/search'

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
}

License

See LICENSE for more information.