API usage in an add-on

Using API in your add-on

The eLabNext API is the method to interact with the data of your eLabNext organization. This also holds through when wanting to implement such functionality within an add-on. The difference here compared to an external script that uses the API is that no access token and set base URL are needed. This is achieved through using the SDK wrapper for the API that is eLabSDK.API.

Implementing API in your add-on

To implement API calls in your add-on, you can make use of the therefore designated SDK function of eLabSDK.API. The advantages of this are:

• No need for an access token as the logged in user credentials are used.
• No need for a base URL as this is determined from the user environment.

These features make it so that any eLabNext user that uses an add-on can make use of the API calls without the need for any hardcoded information. Below is an example of how an eLabSDK.API can be setup to create a new sample:

eLabSDK.API.call({
    method: 'POST',
    path: 'samples',
    body: {
        sampleTypeID: 123,
        name: 'My sample'
    },
    onSuccess: function (xhr, status, response) {
        // Action(s) to undertake 
        // Response is an integer indicating the new sample's ID.
        var newSampleID = response;
    },
    onError: function (xhr, status, response) {
        // Handling when the API call encounters an error
        console.log("something has gone wrong with the API call")
    } 
});

The information that is required for each API call can be found in their respective interactive documentation page. For the above example this is the Create a new sample page. Here you can find information on the API call method, the path and which information goes into the API body. Besides the API call information that can be passed into the eLabSDK.API function, it also contains an onSucces and onError feature, that allows you to easily set up the handling of when the API call has been successfully completed or has run into an error.

Parameter types

Besides the standard API body parameters that can be present, there are also path and query parameters. Below is an example where a call is done retrieving log information for a sample:

eLabSDK.API.Call({ 
    method: 'GET', 
    path: `samples/{sampleID}/logs`, 
    pathParams: { 
        sampleID: sample_id, 
    },
    queryParams: { 
        action: 'UPDATE', 
        sampleMetaKey: 'Location', 
    }
});

Just like for the other variables that can be set for an API call, all information can be found on the the respective documentation page like for this Get sample logs call. The header above each variable section indicates to which parameter type it belongs. Important to note is that for path parameters the parameter needs to be included in the path variable, as shown in the example.