Building an application that uses the changes endpoint (tutorial)

In this guide we will guide you through building an application that uses the changes endpoint of the Proff API.

Prequisites

A basic familiarity with the Proff API is assumed and it is recommended that you have read the Using the Changes endpoint section. It is assumed that the reader is familar with JavaScript (NodeJS) as programming language, although the examples should be fairly easy to understand for programmers coming from a Java, C# or similar background. Finally, an API key is required. With that out of the way, let's start building!

Introduction

Your company has been receiving an increasing number of complaints of invoices sent to wrong addresses and you want to implement a process that automatically updates company names and addresses of your customers. You've been given the task to implement this process. You will receive a file or given access to a a database that contains all the organization numbers of your company's customers that you want to monitor for changes. Exactly how you will receive this list is beyond the scope of this tutorial. Here we assume that it is made accessible as a Set in your program, for example like this:

// Organisation numbers of your customers - could be loaded from database, file, etc
const customers = new Set(['985815534', '978684556', '894629282', '810387882', '925149306'])

Your company would like to receive a list of organization numbers that have changes so they can review the changes. It is not required that you make the actual update of the companies.

Defining constants and HTTP client

Once you have the list of organization numbers, let's first define a couple of useful constants.

The first is the address to the changes endpoint, and the second is the API key. In this example we pick up the API key from the environment variable, but how you do this is entirely up to you, but, make sure you keep it secret and do not commit it to a git repository!

const API_TOKEN = process.env.API_TOKEN // Your API token
const PROFF_API_CHANGES_ENDPOINT = 'https://api.proff.no/changes/register/NO'

Let's also define an instance of axios to use as HTTP client:

// Use any library you like for HTTP requests
const axios = require('axios')
const httpClient = axios.create({
    timeout: 1000,
    headers: {
        'Authorization': `Token ${API_TOKEN}`,
        'api-version': '1.1',
    },
    responseType: 'json'
});

Note that we specify the api-version header here which is recommended for new integrations. We are also specifying a timeout, which we recommend you always do.

Making requests

With that out of the way we can make our first request to the endpoint. Note that we are using async/await here so you should wrap the method call in a async function definition:

const response = await httpClient.get(uri);

Let's examine the response to see if there are any changed docs. If the changedDocs array is empty, there are no changes and we can simply return:

const changedDocs = response.data.changedDocs
if (!changedDocs.length)
    return;

If it is not empty (which usually is the case), we can iterate all elements of the array to see if any of the id's in the array are present in our customers Set. If it is we add it to a new Set - changedCompanies:

const changedCompanies = new Set()

for (const changedDoc of changedDocs) {
    const id = changedDoc.id
    if (customers.has(id)) {
        changedCompanies.add(id)
    }
}

Processing the next batch of results

So far we have only considered the first 1000 results. To finish our implementation we need to put the code we have into a loop, and use the link given in the link object to fetch the next batch of results until there are no more results:

// Get the link to the next batch of results
uri = response.data.link.href

Putting it all together

Putting it all together then may look like the code below. Not that here we also print out some details like the total number of hits, how many changed documents and companies that was changed:

let uri = PROFF_API_CHANGES_ENDPOINT

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

while (true) {
    console.log(`Processing ${uri}`);
    const response = await httpClient.get(uri);

    // Print total number of hits on 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; // No more changes to process

    // Loop through all changedDocs and compare the id to our list of customers
    for (const changedDoc of changedDocs) {
        const id = changedDoc.id
        changeDocsFromApi.push(id)
        if (customers.has(id)) {
            changedCompanies.add(id)
        }
    }

    // Get the link to the next batch of results
    uri = response.data.link.href
}

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

// Print a list of companies with changes
console.log(`Changed companies: ${Array.from(changedCompanies)}`);

There you have it - you have now built an application that utilizes the changes endpoint in Proff API. The next step would be to fetch the updated data for the companies that have changed and output this to a file or update your database, depending on your company's infrastructure setup.