Use the JavaScript client

The Northflank JavaScript client allows you to interact with Northflank via JavaScript code. The JavaScript client can be installed using either NPM or Yarn:

• npm i @northflank/js-client, or
• yarn add @northflank/js-client

You must authenticate the client using an API token. Team members can generate an API token in that team's settings, provided an API role has been created by a member with permissions.

You can then use this token in a context provider, as demonstrated below.

The Northflank API has a default rate limit of 1000 requests per hour, which resets one hour after the first request is sent. You can contact support@northflank.com to request higher API limits.

The details for your rate limit are sent in the header for each response from the Northflank API, which can be accessed with the following keys:

You can access these keys from the rawResponse object returned by the JavaScript Client:

const { data, rawResponse } = await NFClient.get.project({ parameters });

const { headers } = rawResponse;
const limit = headers.get('x-ratelimit-limit');
const remaining = headers.get('x-ratelimit-remaining');
const reset = headers.get('x-ratelimit-reset');

Below is an example of basic usage: setting up the client using an API token, fetching a list of existing projects and then creating a new project.

import { ApiClient, ApiClientInMemoryContextProvider} from '@northflank/js-client';

(async () => {
  // Create context to store credentials.
  const contextProvider = new ApiClientInMemoryContextProvider();
  await contextProvider.addContext({
      name: 'test-context',
      token: '<api-token>', // Use token retrieved from Northflank web interface: Account Settings > API > Tokens > Create API token.
  });

  // Initialize API client.
  const apiClient = new ApiClient(contextProvider);

  // Retrieve list of projects and log to console.
  const projects = (await apiClient.list.projects({})).data.projects;
  console.log(projects);

  // Create a new project.
  await apiClient.create.project({
    data: { name: 'test-project', region: 'europe-west', description: 'test project description' },
  });
})();

Calls using the JavaScript client take a combination of 3 parameters:

• body - a payload or resource definition, usually used when creating a resource,
• parameters - equivalent to path parameters on the API, and
• options - equivalent to query parameters on the API

Have a look at operations such as update service deployment, list builds, and view secret for examples of the different options. You may need to switch to the 'JS client' tab on the right-hand side.

Paginated endpoints (those returning lists), return 50 elements by default. You can use the all() method to return all elements, this will use multiple API calls which count towards your rate limit. For example:

const allResults = apiClient.list.projects.all({})

The pagination object for a response also includes a getNextPage() function, which will return the next set of elements. If there are no more elements to return then the function will not return any elements.

const resFirstPage = await apiClient.list.projects({});
const nextPage = await resFirstPage.pagination?.getNextPage();

The ApiClient constructor also takes an optional second boolean argument, which if set to true will cause the client to throw an error if the request is met with a HTTP error code response.

Responses are in JSON. The response object contains the following keys: