v1
Double column

This documentation covers the Northflank API, CLI, and JavaScript client.

Each page under the sections in the sidebar navigation is dedicated to a single action. For the most part, every action can be performed via the API, CLI, or JavaScript client.

Left column

Each page is split into two halves. The left-hand side of the page describes the action performed by a route, followed by an exact breakdown of any parameters or request body required by that route, as well as any response body that may be returned by that route.

This includes the structure of requests/responses, whether fields are required or optional, data types of fields, and even restrictions on the formatting of fields. Bare in mind that many request/response objects are nested and should be expanded to view their full structure.

Right column

The right-hand side of the page contains the details required to perform the action — this could be the URL of an API route, a command for the CLI, or a method for use in the JavaScript client. The tabs at the top of the right-hand pane allow you to switch between the three.

As well as this information, the right-hand pane also includes example requests and responses that match the definitions on the left. These can provide some more insight into the kind of data that you will actually be working with. When viewing the CLI tab, the right pane also lists all of the possible options for the current command.

When viewing example API requests, the language of the snippet can be changed with the small dropdown in the top right corner.

The Northflank API allows you to interact with Northflank using HTTP requests.

The API is available at https://api.northflank.com.

Requests and responses are both in JSON. Requests should include the header: Content-Type: application/json.

Authentication

Access to most endpoints is restricted and authenticated via a bearer token. Users can generate a personal API token in their account settings. Users can generate a team API token in that team's settings, provided an API token template has been created.

The API token must then be included in the Authorization header for the request:

Authorization: Bearer [YOUR AUTH TOKEN]

The Northflank CLI client allows you to interact with Northflank via the command line. The CLI client can be installed using either NPM or Yarn:

  • npm i -g @northflank/cli, or
  • yarn global add @northflank/cli

Once installed, authenticate yourself using the northflank login command. You will need to create an API token at app.northflank.com.

The CLI client is fully interactive, meaning that it will ask for any parameters needed along the way. However, you always have the option to pass in any required parameters in your commands. For example, after entering the command

northflank get service details

you will be prompted to enter a project ID and a service ID. You can achieve the same result in a single step by using the command

northflank get service details --project <PROJECT_ID> --service <SERVICE_ID>

Authentication and contexts

Contexts allow you to separate different Northflank accounts and preferences when using the CLI client.

For example, you may have a context for your personal Northflank account, and a different context for a team account.

Contexts are created with the northflank login command. You will be guided through the process of naming the context and supplying a token, or you can pass these values in as arguments. See northflank login --help for the full list of options. Once logged in, the active context will be switched automatically.

Once created, contexts can be viewed with northflank context list and switched to with northflank context use <CONTEXT_NAME>.

To set a default project or service within a context, you can use the command

northflank context use project|service <PROJECT_ID|SERVICE_ID>

and you will no longer need to supply a project/service in your commands to use the defaults.

Creating resources

When creating resources on Northflank, you can do so interactively, or you can supply a resource definition. This can be done using the --input or -i option followed by a JSON/YAML string, or by using the --file or -f option followed by the path to a JSON/YAML file containing the definition.

The resource definitions are equivalent to the API request bodies you will find in this documentation.

Help

You can get help at any time by using the --help flag. This includes getting help with specific commands, for example

northflank create project --help

will return helpful information about creating a project.

To see a handy tree view of all possible commands, you can run

northflank command-overview

Extra CLI commands

There are a few CLI-specific commands that do not have an API equivalent, and therefore do not appear alongside API endpoints in this documentation.

These commands are:

northflank forward

  • Port-forwarding for Northflank services and addons. For example northflank forward service allows you to select a service and port forward it so it is available from your localhost.

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

Usage

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.project({})).response.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.

Throwing errors on request failure

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

Responses from the client are of the following format:

export declare type ApiCallResponse<R> = {
  response: R;
  rawResponse: Response;
  request: {
    url: string;
    method: string;
    headers: any;
    body: any;
  };
  error?: {
    code: number;
    message: string;
  };
};

Where response is the JSON response to your query.

© 2021 Northflank Ltd. All rights reserved.