Building an application that uses the Changes endpoint

This tutorial shows you how to build an application that uses the Proff API Changes endpoint.

Prerequisites

This tutorial assumes that you:

• Have a basic understanding of the Proff API
• Have read Using the Changes endpoint
• Are familiar with JavaScript and Node.js
• Have a valid API key

The examples should also be easy to follow if you have experience with Java, C#, or a similar programming language.

Introduction

Your company has received an increasing number of complaints about invoices being sent to incorrect addresses. To address this, you want to implement a process that identifies changes to your customers' company names and addresses.

You have been asked to build this process. You will receive a file or access to a database containing the organization numbers of the customers you want to monitor.

How the customer list is retrieved is outside the scope of this tutorial. We assume that the organization numbers are available as a JavaScript Set:

// Customer organization numbers
// These could be loaded from a database, file, or another source
const customers = new Set([
  '985815534',
  '978684556',
  '894629282',
  '810387882',
  '925149306'
]);

The application will generate a list of customer organization numbers for companies that have changed. Updating the company records is outside the scope of this tutorial.

Defining constants and the HTTP client

First, define the URL for the Changes endpoint and retrieve your API token from an environment variable.

Keep your API token secret and never commit it to a Git repository.

// Retrieve the API token from an environment variable
const API_TOKEN = process.env.API_TOKEN;

const PROFF_API_CHANGES_ENDPOINT =
  'https://api.proff.no/changes/register/NO';

Next, create an Axios HTTP client:

const axios = require('axios');

const httpClient = axios.create({
  timeout: 1000,
  headers: {
    Authorization: `Token ${API_TOKEN}`
  },
  responseType: 'json'
});

Always specify a timeout when making HTTP requests.

Making requests

You can now make your first request to the endpoint.

The following examples use async and await, so the code must be executed inside an asynchronous function:

const response = await httpClient.get(uri);

Check the response for changed documents. If the changedDocs array is empty, there are no more changes to process:

const changedDocs = response.data.changedDocs;

if (!changedDocs.length) {
  return;
}

If the array contains results, compare each company ID with the organization numbers in the customers set. Add matching organization numbers to a new set named changedCompanies:

const changedCompanies = new Set();

for (const changedDoc of changedDocs) {
  const id = changedDoc.id;

  if (customers.has(id)) {
    changedCompanies.add(id);
  }
}

A Set ensures that each organization number appears only once.

Processing the next batch of results

Each response contains up to 1,000 changed documents.

To process all available results, place the request and processing logic inside a loop. Use the URL provided by the response to retrieve the next batch:

// Get the URL for the next batch of results
uri = response.data.link.href;

Continue until the API returns an empty changedDocs array.

Putting it all together

The complete processing loop looks like this:

let uri = PROFF_API_CHANGES_ENDPOINT;

const changedCompanies = new Set();
const changeDocsFromApi = [];

while (true) {
  console.log(`Processing ${uri}`);

  const response = await httpClient.get(uri);

  // Display the total number of results from the first request
  if (uri === PROFF_API_CHANGES_ENDPOINT) {
    const numberOfHits = response.data.numberOfHits;
    console.log(`Processing ${numberOfHits} changes...`);
  }

  const changedDocs = response.data.changedDocs;

  if (!changedDocs.length) {
    break;
  }

  // Compare each changed company with the customer list
  for (const changedDoc of changedDocs) {
    const id = changedDoc.id;

    changeDocsFromApi.push(id);

    if (customers.has(id)) {
      changedCompanies.add(id);
    }
  }

  // Get the URL for the next batch of results
  uri = response.data.link.href;
}

console.log(`Processed ${changeDocsFromApi.length} changes.`);
console.log(
  `Processed ${new Set(changeDocsFromApi).size} unique changed companies.`
);

// Display customers with registered changes
console.log(
  `Changed customers: ${Array.from(changedCompanies).join(', ')}`
);

You have now built an application that retrieves changes from the Proff API and identifies which of your customers have been affected.

The next step could be to retrieve the updated company information and export it to a file or update your database, depending on your infrastructure and requirements.