Scoutnet Node.js API Client

This is an API client for the Scoutnet API developed and maintained by Scouternas e-tjänster. It is automatically generated from the Scoutnet OpenAPI document.

The client uses openapi-typescript and openapi-fetch under the hood. This NPM package exports all types generated by openapi-typescript as well as a modified version of the createClient method from openapi-fetch. This means that you can use just the types if you need to build something very custom. For complete usage instructions, check out their documentation.

Installation

The client is available on NPM:

npm i @scouterna/scoutnet

Usage

Creating the client

You must always start by creating an instance of the API client. This ensures all requests will be fully type safe.

import { createClient } from '@scouterna/scoutnet'

const client = createClient();

You can pass options when creating the client that will apply to all requests. For example, you might want to use a different server during development.

const client = createClient({
  baseUrl: 'https://s1.test.custard.no/api'
});

Making requests

When making requests you provide the endpoint you want to call, and the types are automatically inferred. Because all endpoints in the Scoutnet API have unique access keys this is also where you set the Authorization header.

const result = await client.GET("/project/get/participants", {
  headers: {
    Authorization: createAuthorizationHeader({
      resourceId: '12345',
      key: '80vn4...n724',
    }),
  },
});

if ('error' in result) {
  // Handle the error properly
  throw new Error(`Request failed with status code ${result.response.status}`);
}

console.log(data.participants);
//               ^ Access fully typed properties

There are two important notes to be made here.

First, make sure to use if ('error' in result) to check if there is an error as in the example above and not just if (result.error). Since Scoutnet returns an empty body on errors such as 401 the latter will pass even though there is an error.

Second, often times you will receive multiple levels of data. Consider the following simplified example of a response:

{
  "first_name": "Janne",
  "last_name": "Långben",
  "contact_info": {
    "1": "0701 23 45 67"
  }
}

As you can see the contact_info property contains an object of arbitrary data. If we instead imagine there was no contact info the response would look like this:

{
  "first_name": "Janne",
  "last_name": "Långben",
  "contact_info": []
}

Notice how contact_info suddenly became an empty array. This is a quirk of the Scoutnet API that happens every time there is an empty object and you will have to handle it accordingly. The return type of the API methods should help you catch these cases.