DDB Typescript/Javascript Client

Full documentation of the ddb-js typescript package, which simplifies access to the DDB API using typescript.

Note for external users - many of the links in the following section refer to internal applications. Please speak to your project team for support.

Prerequisites

You'll need the software below installed on your environment

• NodeJS v16.x+
• npm v8.x+

see how to download these packages here (opens new window)

Authenticate to the Azure npm registry

ddb-js packages are hosted on the (private) Azure npm package registry. In order to install it you must authenticate, see below options below.

Windows

To use npm packages, get npm (which comes with Node.js) and the vsts-npm-auth helper.

Step 1

Install the Prerequisites

Step 2

Run this command

npm install -g vsts-npm-auth --registry https://registry.npmjs.com --always-auth false

Step 3

Add a .npmrc to your project, in the same directory as your package.json

@ddb:registry=https://pkgs.dev.azure.com/ovearup/_packaging/ddb/npm/registry/

always-auth=true

Then, run vsts-npm-auth to get an Azure Artifacts token added to your user-level .npmrc file.

vsts-npm-auth -config .npmrc

Note: You don't need to do this every time. npm will give you a 401 Unauthorized error when you need to run it again. Having issues? See the instructions for using a Personal Access Token to authenticate.

Others

Step 1

Install the Prerequisites

Step 2

Add a .npmrc to your project, in the same directory as your package.json

@ddb:registry=https://pkgs.dev.azure.com/ovearup/_packaging/ddb/npm/registry/

always-auth=true

Step 3

Copy the code below to your user .npmrc (~/.npmrc).

; begin auth token
//pkgs.dev.azure.com/ovearup/_packaging/ddb/npm/registry/:username=ovearup
//pkgs.dev.azure.com/ovearup/_packaging/ddb/npm/registry/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
//pkgs.dev.azure.com/ovearup/_packaging/ddb/npm/registry/:email=[EMAIL]
//pkgs.dev.azure.com/ovearup/_packaging/ddb/npm/:username=ovearup
//pkgs.dev.azure.com/ovearup/_packaging/ddb/npm/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
//pkgs.dev.azure.com/ovearup/_packaging/ddb/npm/:email=[EMAIL]
; end auth token

Step 4

Generate a Personal Access Token (opens new window) with Packaging read & write scopes.

Step 5

Base64 encode the personal access token from Step 4.

One safe and secure method of Base64 encoding a string is to:

From a command/shell prompt run:

node -e "require('readline') .createInterface({input:process.stdin,output:process.stdout,historySize:0}) .question('PAT> ',p => { b64=Buffer.from(p.trim()).toString('base64');console.log(b64);process.exit(); })"

Paste your personal access token value and press Enter/Return Copy the Base64 encoded value

Step 6

Replace both BASE64_ENCODED_PERSONAL_ACCESS_TOKEN values in your user .npmrc file with your personal access token from Step 5.

Replace both [EMAIL] values in your user .npmrc file with your email.

Installation

After authenticating as described above @ddb packages can be installed via npm. All microservices can be installed separately

npm install @ddb/comments-service
npm install @ddb/environment-context-service
npm install @ddb/parameter-metadata-service
npm install @ddb/parameter-service
npm install @ddb/qa-service
npm install @ddb/reference-data-service
npm install @ddb/user-service

Step by Step Guide

Configuartion

This exmaple is for @ddb/comments-service

import { CommentsApi, Configuration, Environment } from "@ddb/comments-service";

// created a new configuration class
const config = new Configuration()

// specify the required environment, the default is production if the basepath isnt set
config.basePath = Environment.sandbox

// pass in the access token, note only pass in the accessToken, it will prefix with 'Bearer'
config.accessToken = 'token'

// Initialise the new class, with the config
const commentsAPI = new CommentsApi(config)

Using the API

All methods are initiated on the class, and exmaple of how to call them are below

const comments = await commentsAPI.getComments()

Refer to the typescript interfaces to understand the parameters, required in the request, and also the responses back from the function.

Note: If you have IntelliSense installed youll be directed

Developer Information

The repository is located here (opens new window). See how to contribute (opens new window).