nexxOMNIA API
Search…
NodeJS
Introduction
You can find all necessary Code for Download and Changelogs always here:
GitHub - 3qnexx/APIClient-NodeJS: nexxOMNIA Client for NodeJS
GitHub
The NodeJS SDK for the nexxOMNIA API needs at least NodeJS 12.* as Environment.
1
npm install nexxomnia-api-nodejs
Copied!
1
const {APIClient} = require("nexxomnia-api-nodejs");
Copied!
A very simple Example could be
1
const {APIClient, MediaCall, streamtypes} = require("nexxomnia-api-nodejs");
2
​
3
let apiclient = new APIClient();
4
apiclient.configure(999,"API-SECRET","SESSION-ID");
5
​
6
let apicall = new MediaCall(streamtypes.VIDEO);
7
apicall.latest();
8
​
9
let result = await apiclient.call(apicall);
10
​
11
let obj=result.getResultIterator(true);
12
for(let el of obj){
13
console.log(el.getGeneral().getID());
14
}
Copied!
General Usage
For any API Call, two Classes have to be instantiated. The
APIClienthas to be created only once and configured with the target Domain ID, the Domain Secret and (in most Cases) a valid Session ID - in most cases, that would be the Management Session ID.The
APIClientwill execute a valid APICall. There are many different APICallClasses for different Aspects of the API, but they all work in a similar Way.All API Methods, as described in this Documentation, are available on the corresponding
APICallClass. In most cases, the APICallClass Method is "humanized" and the Naming is less technical.Nearly every API Method can be configured by Parameters and/or Modifiers. Consequently, each
APICall Class exposes a getParameters() and a getModifiers() Method, which return Helper Classes for easier accessing the correct Parameters here:1
let apicall = new MediaCall(streamtypes.VIDEO);
2
apicall.getParameters().setLimit(50);
3
apicall.getParameters().set("limit",50);
Copied!
In this simple Example, the basic Way to set Parameters is shown (the
setMethod). Every valid Parameter though has also an explicit Setter (here setLimit), which additionally check Consistency and Validity of the given Parameter.Methods with unique Parameters (like in the /manage API Endpoint), expose these Parameters directly on the Method and handle the necessary Parameter Logic themselves.
The call Method of the
APIClient takes the configured API Call and directly starts it. It returns an Instance of the APIResult Class then, which can be handled like this:1
let result = apiclient.call(apicall);
2
​
3
if(result.isSuccess()){
4
​
5
result.getRawResponse();
6
result.getResult();
7
8
if(result.supportsResultObject()){
9
result.getResultObject();
10
}
11
12
if(result.supportsIterator()){
13
result.getResultIterator(true);
14
}
15
​
16
}else{
17
console.log(result.getMetadata().getErrorHint());
18
}
Copied!
The
APIResultClass can directly return the received JSON via getRawResponse- or, only the "result" Part of the Response via getResult.For more advanced Usage, it can also return an Instance of the
ResultObjectClass, which allows to query the JSON in a more human Way:1
id = result.getRawResponse()["result"]["general"]["ID"];
2
id = result.getResultObject().getGeneral().getID();
Copied!
Especially the media API returns very often Lists of Media Objects. For Iterating directly over the JSON Array, the result Class exposes an Iterator via
getResultIterator. The Iterator itself can return the pure JSON Objects or ResultObject Class Instances as above.Creating new Elements
Media Creation via API
The SDK allows also to create new Media. Technically, there are Media Types, that need an initial File (like a Video), and Media Types, that exist of Data alone (an Article for example).
File-driven Media Types can be created by giving a URL, that the API will use to download and process the Input and create an Item from it:
1
let videoURL="https://example.com/video.mp4";
2
​
3
let apicall = new MediaManagementCall();
4
apicall.setStreamtype(streamtypes.VIDEO);
5
apicall.createFromURL(videoURL);
6
​
7
let result = apiclient.call(apicall);
8
​
9
if(result.isSuccess()){
10
// the ID of the new Video via ResultObject:
11
videoID = result.getResultObject().getGeneratedID();
12
​
13
// or via JSON Objects:
14
videoID = result.getResult()['itemupdate']['generatedID'];
15
}
Copied!
Data-driven Media Types will be created like this:
1
let apicall = new MediaManagementCall();
2
apicall.setStreamtype(streamtypes.ARTICLE);
3
apicall.createFromData("Article Title","Article Refnr");
4
​
5
let result = apiclient.call(apicall);
6
​
7
if(result.isSuccess()){
8
// the ID of the new Article via ResultObject:
9
articleID = result.getResultObject().getGeneratedID();
10
​
11
// or via JSON Objects:
12
articleID = result.getResult()['itemupdate']['generatedID'];
13
​
14
}
Copied!
​
Creating Structure Elements
Structure Elements like Channels, Formats and Categories are not Media Items. They exist on the Domain Level only and can be created like Data-driven Elements via API:
1
let apicall = new DomainManagementCall();
2
apicall.addChannel({'title':'Channel','refnr':'123','parent':0,'pos':1});
3
​
4
let result = apiclient.call(apicall);
5
​
6
if(result.isSuccess()){
7
// the ID of the new Channel
8
channelID = result.getResultObject().getGeneratedID();
9
​
10
// or via JSON Objects:
11
channelID = result.getResult()['itemupdate']['generatedID'];
12
​
13
}
Copied!
The Attributes for this Example are listed in the Domain Management API:
​
Media Creation via UploadHandler
Alternatively, you can upload a local File directly with the
UploadHandlerClass:1
const {APIClient, UploadHandler} = require("nexxomnia-api-nodejs");
2
​
3
let localPath="/var/www/myfolder/video.mp4";
4
​
5
let uploadhandler = new UploadHandler();
6
uploadhandler.setAPIClient(apiclient);
7
​
8
let apiresult = uploadhandler->uploadMedia(localPath,streamtypes.VIDEO);
9
​
10
//the UploadHandler returns an API Result, that can be used as usual
11
let videoID = apiresult.getResultObject().getGeneratedID();
Copied!
Using the UploadHandler
Besides the pure Upload of new Media Files, the UploadHandler offers even more Helpers for all API Endpoints, that need a phsyical File (like Covers and Captions):
1
let coverPath="/var/www/myfolder/cover.jpg";
2
let captionPath="/var/www/myfolder/caption.vtt";
3
​
4
let uploadhandler = new UploadHandler();
5
uploadhandler.setAPIClient(apiclient);
6
​
7
uploadhandler.setMediaCover(coverPath,streamtypes.VIDEO,videoID);
8
uploadhandler.addMediaCaptions(captionPath,streamtypes.VIDEO,videoID,"es");
Copied!
Available APICall Classes
Media API
The most important Difference to other Classes here is the need for setting the target Streamtype (in the Constructor or via explicit Method). By default, the Class uses "video" as Streamtype. You can use the Enum Class
streamtypes to be sure or just use a String.1
apicall.setStreamtype(streamtypes.IMAGE);
Copied!
The Media API offers by far the highest Amount of Modifiers and Parameters, which are exposed as described above. It also nearly always returns Lists of Media, which implies using the Interator Object on the result Class.
Very often, it is necessary to get all possible Results in one Array. The API itself does not return more than 100 Elements per Call, but if all possible Results are needd, the
callMethod of the APIClientoffers a second Parameter, which will handle the Parameters and Interating over the API Responses to construct a APIResultObject with indeed all Result Objects.Management APIs
As the Management API offers by far the most Methods, the API Client offers MediaManagement and DomainManagement Classes for the corresponding Method Helpers.
Like the Media API, the Classes offer a
setStreamtypeand a setItemMethod, which is extremely helpfull especially on Media Management, where one specific Media Item of a specific Streamtype should be modified.​
Statistics API
The Statistics API returns in nearly every case lists of Key=>Value Pairs. Therefore, the Usage of the
getResultMethod of the responseObject is is most cases sufficient.Please notice, that some Methods can return huge Lists. As Paging is not supported in this API, you can set the Limit to higher Values (like 100000). Furthermore, this API might take longer than all other APIs, as it returns realtime Data. The apiclient therefore sets a Timeout of 30 Seconds by default, it Endpoints of this API are called. It is possible though to raise this Value even more:
1
apiclient.setTimeout(60);
Copied!
​
Domain API
The Domain API exposes various structural Objects, that are connected to a Domain. The classic Example is a List of Channels via
getChannels. In most Cases, the response should be iterated over with an Iterator, but as most Lists are very short and Paging is (in most Cases) not supported, the getResultMethod is enough.​
System API
The System API is very straight forward, as it basically only returns Objects/Arrays of System Constants. The Usage of the
getResultMethod of the APIResponseObject is is most cases sufficient.​
Session API
The Session API is available in the SDK, but in nearly every Case, this Backend SDK should use the constant "Management Session", given by 3Q nexx. Nevertheless, it is possible to start and extend Sessions with this Class, if needed.
​
Processing API
The most important Method of the Processing API is the MultiTask Method, which allows to query multiple API Endpoints at the same time. To make sure, the Parameters are built correctly, each Task, that is given to the Method is itself a Class. It is used like this:
1
let apicall = new ProcessingCall();
2
​
3
let tasks = [];
4
let task = new Task("task-1");
5
task.setEndpoint(streamtypes.AUDIO);
6
task.setMethod("byid");
7
task.setItem(999);
8
tasks.push(task);
9
​
10
apicall.multiTask(tasks);
Copied!
​
Custom APICall
For advanced Usage, you can omit all predefined Methods and Helpers and use a custom APICall. Please notice, that in this Case, you have to be very sure about the right Endpoints, Methods, HTTP Verbs and Parameters.
1
let apicall = new CustomCall();
2
apicall.setVerb(defaults.VERB_GET);
3
apicall.setPath("/videos/byid/123");
4
apicall.getParameters().set("additionalFields","channel");
Copied!
Last modified 9mo ago