Skip to content

JavaScript

Sample code to interact with the Domino REST API in JavaScript.

Note

Know your runtime.

The fetch API works in all modern browsers. However, it is only available in current versions of the server-side JavaScript environments, such as NodeJS, so always check the documentation.

Look at the three functions that can give you a head start.

URL collection

Instead of sprinkling URLs across the JS functions, use global objects to abstract them away:

const urls = {
  login: '/api/v1/auth',
  list: '/api/v1/query?dataSource=approvals&action=execute'
};

You want to adjust the list to your needs.

Login function

The function returns the bearer or throws an error.

const login = async (user, pwd) => {
  try {
    const response = await fetch(urls.login, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ username: user, password: pwd })
    });
    const jBody = await response.json();
    if (jBody.bearer) {
      return jBody.bearer;
    }
    throw new Error('No bearer returned');
  } catch (err) {
    console.err(err);
    throw err;
  }
};

Calling an API

In this example, you call the query endpoint and return the JSON when successful.

const loadApprovals = async (bearer, status) => {
  const query = {
    query: `form = 'equipment' and status = '${status}'`,
    viewRefresh: true,
    noViews: false
  };

  const options = {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${bearer}`
    },
    body: JSON.stringify(query)
  };

  try {
    const response = await fetch(urls.list, options);
    if (response.status != 200) {
      throw new Error(
        `Query returned failure status ${response.status}: ${response.statusText}`
      );
    }
    const jBody = await response.json();
    // Add additional checks here
    return jBody;
  } catch (err) {
    console.error(err);
    throw err;
  }
};

Processing list results

The Domino REST API uses chunked returns (RFC9112) for anything that returns an array and thus could return a lot of data. Instead of calling await response.json(), use the HTTP Streams API. Browsers implement that API in native code for speedy processing. A fetch request returns a readable stream that can be processed using a TransformStream (a stream that is both readable and writable) to then be consumed by a writable stream. There are a few steps involved:

Stream Steps

All of these steps get tied together using the pipeThrough method calls. Look at it step by step:

Byte to String

The first part "Byte to String" is built-in using a TextDecoderStream. As a result, you get a stream of characters, and you now chop into parts.

String to lines

String to lines is your first TransformStream. An instance needs to implement two methods:

  • transform(incoming, controller) reads incoming data and eventually call the controller's enqueue(output) method 0:n times
  • flush(controller) called for cleanup

In this case, the incoming character stream is chopped into lines.

/* Chops arriving chunks along new lines,
    takes into account that a chunk might end middle of line */
const splitStream = () => {
  const splitOn = '\n';
  let buffer = '';
  return new TransformStream({
    transform(chunk, controller) {
      buffer += chunk;
      const parts = buffer.split(splitOn);
      parts.slice(0, -1).forEach((part) => controller.enqueue(part));
      buffer = parts[parts.length - 1];
    },
    flush(controller) {
      if (buffer) controller.enqueue(buffer);
    }
  });
};

String to JSON

You chop of the leading [ and trailing ] and user JSON.parse(). In production code, you could pack the parsing in a try/catch block.

/* Parses JSON if row looks like JSON (with eventual comma at end of line) */
const parseJSON = () => {
  return new TransformStream({
    transform(chunk, controller) {
      // IGNORES THE [ and ]
      if (chunk.endsWith(',')) {
        controller.enqueue(JSON.parse(chunk.slice(0, -1)));
      } else if (chunk.endsWith('}')) {
        controller.enqueue(JSON.parse(part));
      }
    }
  });
};

JSON to HTML

This depends very much on your intended output, a table, cards, graphics etc. For this example, you create table rows. You could use a more sophisticated approach using parameters to drive the table shape, your JS skills is going to be helpful.

const rowMaker = () => {
  return new TransformStream({
    transform(json, controller) {
      const row = document.createElement('tr');
      const col1 = document.createElement('td');
      col1.innerText = json.name ?? 'n/a';
      const col2 = document.createElement('td');
      col2.innerText = json.age ?? 'unknown';
      row.appendChild(col1);
      row.appendChild(col2);
      controller.enqueue(row));
    },
    flush(controller) {
      // No action here
    }
  });
};

Update the UI

You can use a WritableStream to update the UI.

const updateUI = (parent) => {
  return new WritableStream({
    write(child, controller) {
      parent.appendChild(child);
    }
  });
};

Putting it all together

With the object instances in place, you can stick the pipe together to execute the flow based on this article.

const insertPoint = document.getElementById('resultTableBody');
await httpResponse = fetch(url, options);
await httpResponse.body
  .pipeThrough(new TextDecoderStream())
  .pipeThrough(splitStream())
  .pipeThrough(parseJSON())
  .pipeThrough(rowMaker())
  .pipeTo(updateUI(insertPoint));

Considerations

  • Once you retrieve the bearer, you need to keep it somewhere. A simple, but not very secure option is to save it into window.bearer.

  • Advantage: goes away when window closes

  • Challenge: can be read from elsewhere unless your CSP is tightly managed

    A common way is to use local storage, which also needs to be handled carefully.

  • Tighten your CSP and only use HTTPS.

  • Besides extracting the bearer, you could grab the expiry time and create a function that first validates the token's lifespan before making a call.