@infoxchange/iss4

ISS v4 REST API Node.js Client

This package provides a Node.js client for interacting with the ISS v4 REST API. This client has been transpiled from the python client https://github.com/InfoxchangeTS/iss-v4-rest-python-client

Installation

npm install iss-v4-rest-nodejs-client

Usage

Basic Usage

import { ISSV4APIClient } from 'iss-v4-rest-nodejs-client';

// Initialize the client with JWT authentication
const client = new ISSV4APIClient(
  'https://api.example.com/api/',
  {},
  'client_id',
  'client_secret'
);

// Or with Basic token authentication
import { BasicTokenSession } from 'iss-v4-rest-nodejs-client';

const client = new ISSV4APIClient(
  'https://api.example.com/api/',
  { session: BasicTokenSession },
  'your_token'
);

// Directory search provides a simple yet powerfull parameter based method for a simpler search experience
async function simpleSearch() {
  try {
    const results = await client.directorySearch({
      name: 'health services',
      lga: 'city of yarra',
      fields: '*'
    });
    console.log(results);
  } catch (error) {
    console.error('Search failed:', error);
  }
}

// Advanced search is provided via the search endpoint and takes Appsearch based filters and boosts 
async function advancedSearch() {
  try {
    const results = await client.search(
      'search term', 
      { filter_key: 'filter_value' }
    );
    console.log(results);
  } catch (error) {
    console.error('Search failed:', error);
  }
}

// Entity operations example
async function createOrganisation() {
  try {
    const response = await client.createOrganisation({
      name: 'Test Organisation',
      // Other fields...
    });
    console.log('Organisation created:', response.data);
  } catch (error) {
    console.error('Failed to create organisation:', error);
  }
}

Authentication

The client supports two authentication methods:

• JWT authentication (default)
• Basic token authentication

JWT Authentication

const client = new ISSV4APIClient(
  'https://api.example.com/api/',
  {},
  'client_id',
  'client_secret'
);

Basic Token Authentication

import { BasicTokenSession } from 'iss-v4-rest-nodejs-client';

const client = new ISSV4APIClient(
  'https://api.example.com/api/',
  { session: BasicTokenSession },
  'your_token'
);

Query Parameters

When working with list operations, you can provide query parameters to filter and paginate results:

// Get organisations with pagination
const organisations = await client.organisations(undefined, { limit: '50', offset: '10' });

// Get services with a search term and filters
const services = await client.services(
  { name: 'Health' },  // search term
  { active: 'true' }   // query parameters
);

The client automatically handles various parameter formats, including:

• String values (e.g., { limit: '50' })
• Array values (e.g., { limit: ['50'] })
• Mixed values (e.g., { limit: '50', tags: ['tag1', 'tag2'] })

Note: For array parameters, the client uses the first value in the array when making API requests.

API Reference

The client provides methods for interacting with all the endpoints of the ISS v4 API.

Search Operations

• search(term, filters, boosts, serialiser, options) - Search ISS v4
• directorySearch(queryParams) - Directory search with GET parameters
• searchExplain(term, filters, boosts, serialiser, options) - Explain search query
• searchElasticsearch(query, params, analyticsQuery, analyticsTags) - Submit an Elasticsearch query
• multiSearch(queries) - Perform a multi-search
• querySuggestion(query, options) - Get search suggestions

Organisation Operations

• organisations(searchTerm, params) - Get a list of organisations
• organisationExists(entityId) - Check if an organisation exists
• fetchOrganisation(entityId) - Fetch an organisation
• createOrganisation(data) - Create an organisation
• updateOrganisation(entityId, data) - Update an organisation
• deleteOrganisation(entityId) - Delete an organisation
• createOrUpdateOrganisation(entityId, data) - Create or update an organisation

Site Operations

• sites(searchTerm, params) - Get a list of sites
• siteExists(entityId) - Check if a site exists
• fetchSite(entityId) - Fetch a site
• createSite(data) - Create a site
• updateSite(entityId, data) - Update a site
• deleteSite(entityId) - Delete a site
• createOrUpdateSite(entityId, data) - Create or update a site

Service Operations

• services(searchTerm, params) - Get a list of services
• serviceExists(entityId) - Check if a service exists
• fetchService(entityId) - Fetch a service
• createService(data) - Create a service
• updateService(entityId, data) - Update a service
• deleteService(entityId) - Delete a service
• createOrUpdateService(entityId, data) - Create or update a service
• fetchServiceType(entityId) - Fetch a service type
• listServiceTypes(params) - List service types

Event Operations

• listEvents(queryParams) - List events
• eventExists(entityId) - Check if an event exists
• fetchEvent(entityId) - Fetch an event
• createEvent(data) - Create an event
• updateEvent(entityId, data) - Update an event
• deleteEvent(entityId) - Delete an event
• createOrUpdateEvent(entityId, data) - Create or update an event

Other Operations

• listAgeGroups(queryParams) - List age groups
• fetchAgeGroup(entityId) - Fetch an age group
• listDatasets(queryParams) - List datasets
• fetchDataset(entityId) - Fetch a dataset
• listCrisisKeywords(queryParams) - List crisis keywords
• listRelatedCrisisKeywords(terms) - List related crisis keywords
• fetchCrisisKeyword(entityId) - Fetch a crisis keyword
• createCrisisKeyword(data) - Create a crisis keyword
• deleteCrisisKeyword(entityId) - Delete a crisis keyword
• listLanguages(queryParams) - List languages
• fetchLanguage(entityId) - Fetch a language
• analyticsQueries(options) - Fetch query analytics
• fetchByExternalId(externalId, organisation) - Fetch by external ID
• suggest(suggestionType, start) - Get suggestions

Development

Setup

# Install dependencies
yarn install

# Build
yarn run build

# Run tests
yarn test

Testing

The package includes a comprehensive test suite:

# Run all tests
yarn test

# Run with coverage
yarn test -- --coverage