@studyportals/domain-client

Domain Client

A lightweight client for fetching data from the Domain API and returning it as strongly typed classes defined by the Domain API.

Installation

npm install @studyportals/domain-client --save

Default usage

Instantiate your client class (ProgrammeCard client as example) with all parameters:

const client = new ProgrammeCardClient(
    domainApiUrl, // The url to the Domain API endpoint
    apiKey, // The API key provided by PLOP for your implementation
    probabilitySeed // Number between 1 and 100 (inclusive)
);

Fetch your model using the fetch() method with the requested ID (in this example programme ID):

const card: IProgrammeCard = await client.fetch(5);

Or get multiple using fetchMultiple() with the requested IDs (in this example programme IDs):

const cards: IProgrammeCard[] = await client.fetchMultiple([5, 9, 13]);

Some functions are accompanied by a canShow function that indicates its availability. If the value is not set the function will throw a PropertyNotAvailableException:

const card: IProgrammeCard = await client.fetch(5);

// Might throw PropertyNotAvailableException
const cover: ICover = card.getCover();

// Safe behaviour
if (card.canShowCover()) {
    const cover: ICover = card.getCover();
}

Separated usage

In some cases you might want to separate the fetching of the information from the usage of that information; for instance getting the information in your back-end service and passing it to the front-end application for usage.

First instantiate your client class with all parameters:

const client = new ProgrammeCardClient(
    domainApiUrl, // The url to the Domain API endpoint
    apiKey, // The API key provided by PLOP for your implementation
    probabilitySeed // Number between 1 and 100 (inclusive)
);

To do this you can use the fetchDescription() method instead and encode it as JSON:

const card: IModelDescription = await client.fetchDescription(5);
const jsonData: string = JSON.stringify(card);

Or use the fetchMultipleDescriptions() function to fetch multiple descriptions:

const cards: IModelDescription[] = await client.fetchMultipleDescriptions([5, 9, 13]);
const jsonData: string = JSON.stringify(cards);

When you're ready to use the information in the models you can use the existing client or instantiate a new one without parameters:

const client = new ProgrammeCardClient();

After which you can use the fromDescription() and fromDescriptions() functions to retrieve your models:

const descriptions: IModelDescription[] = JSON.parse(jsonData);
const card: IProgrammeCard = client.fromDescription(descriptions[0]);
const cards: IProgrammeCard[] = client.fromDescriptions(descriptions);

Note that creating a client without providing the required parameters will result in all network functionalities of the client being unavailable. In this case the following functions will throw a ClientException:

await client.fetch(1);
await client.fetchMultiple([5, 9, 13]);
await client.fetchDescription(1);
await client.fetchMultipleDescriptions([5, 9, 13]);