Web API Package¶
The TRAC platform API is available as a JavaScript package on NPM, for building web applications to run directly in the browser.
https://www.npmjs.com/package/trac-web-api
# TRAC Web API
*TRAC is a next-generation data and analytics platform for use in highly regulated environments*
The TRAC web API provides a structured interface for developing web applications to run on the TRAC platform.
It is based on the popular [protobuf.js](https://www.npmjs.com/package/protobufjs) framework and uses the
highly optimised gRPC-Web protocol for transport. The package supports both JavaScript and TypeScript and
provides everything needed to communicate with the TRAC platform directly from a web browser, no additional
development tooling, setup or middleware is required. Inline documentation is available for IDEs that support it.
Documentation for the TRAC platform is available at
[trac-platform.readthedocs.io](https://trac-platform.readthedocs.io).
## Installing the web API package
To install the web API package in your project:
npm install --save trac-web-api
## Using the web API in an application
Each of the TRAC services has a single public API class, which can be instantiated with just two lines of code.
import {trac} from 'trac-web-api';
class Example1 {
constructor() {
// 1. Create an RPC implementation, you need one for each API class
const metaApiRpcImpl = trac.setup.createWebRpcImpl(trac.api.TracMetadataApi);
// 2. Create the API instance using the corresponding RPC implementation
this.metaApi = new trac.api.TracMetadataApi(metaApiRpcImpl);
}
...
The API methods can be called as JavaScript methods on the API classes, both futures and callbacks are supported.
exampleSearchWithFutures(tenant, searchParams) {
const searchRequest = {
tenant: tenant,
searchParams: searchParams
};
// API call using JavaScript futures
return this.metaApi.search(searchRequest)
.then(response => {
// handle response
console.log(response);
})
.catch(err => {
// handle error
console.log(err)
});
}
exampleSearcWithCallbacks(tenant, searchParams) {
const searchRequest = {
tenant: tenant,
searchParams: searchParams
};
// API call using Node-style callbcks
this.metaApi.search(searchRequest, (err, response) => {
if (err) {
// handle error
console.log(err);
}
else {
// handle response
console.log(response);
}
});
}
buildSearchParams() {
// An example search that could be used for the above calls
const exampleSearchParams = {
objectType: trac.metadata.ObjectType.MODEL,
search: { logical: {
operator: trac.metadata.LogicalOperator.AND,
expr: [
{ term: {
attrName: "model_type",
attrType: trac.metadata.BasicType.STRING,
operator: trac.metadata.SearchOperator.EQ,
searchValue: {
type: { basicType: trac.metadata.BasicType.STRING },
stringValue: "acme_widget_model"
}
}},
{ term: {
attrName: "model_owner",
attrType: trac.metadata.BasicType.STRING,
operator: trac.metadata.SearchOperator.EQ,
searchValue: {
type: { basicType: trac.metadata.BasicType.STRING },
stringValue: "wile.e.cyote"
}
}},
]
}}
}
const err = trac.metadata.SearchParameters.verify(exampleSearchParams);
if (err)
throw err;
return trac.metadata.SearchParameters.create(exampleSearchParams);
}
To learn how to build applications on TRAC, check out the
[application development section](https://trac-platform.readthedocs.io/en/stable/app_dev)
in our online documentation. It may also be helpful to look at the documentation of
[protobuf.js](https://www.npmjs.com/package/protobufjs),
which is used to generate the TRAC API classes for the web API package.
# Running a local instance of TRAC for development
Often it will be helpful to run a local instance of TRAC when developing against the web API, to test your API calls
against a real implementation without needing to run your full build pipeline and push to a dev/test server.
There are no pre-built packages (yet!) for the TRAC platform services. To build and run the platform from source,
follow the instructions in the main README file in the root of the
[TRAC source code repository](https://github.com/accenture/trac).
To avoid any compatibility issues, make sure you check out the version tag that matches your version of the web API.
For a local dev setup, you can use the TRAC gateway to route both your app content and API calls. Look in the
main code repo under etc/ for an example configuration file for the gateway, which includes an example of pointing
a route at your local dev server, whether that's the one in your IDE or WebPack or whatever your favourite dev server
tool is. Once your you dev server running and the gateway is configured, access your app through the gateway. You will
see API calls redirected to the appropriate TRAC services.
## Mocking the API services for rapid development and unit testing
The simplest way to mock the API classes is to extend the API class you want to mock and just override the methods
you are interested in to return your test data. Some simple scaffolding will allow for support of both futures and
callbacks (if you are sticking to one pattern this may not be necessary). It is also probably helpful to throw an
error for methods that are not available in the mock implementation.
Here is a quick example of one way this could be done.
class LocalImpl extends trac.api.TracMetadataApi {
// Set an RPC impl to throw an error for methods that have not been mocked
constructor() {
super(() => { throw new Error("Not implemented locally")});
}
// Helper function to handle both future and callback patterns
callbackOrFuture(callback, err, response) {
if (callback)
callback(err, response);
else if (err)
return Promise.reject(err);
else
return Promise.resolve(response);
}
// Add mock implementations for whichever methods are needed...
search(request, callback) {
try {
// Some logic here, optionally using the contents of request
const dummyResponse = {searchResult: []};
return this.callbackOrFuture(callback, null, dummyResponse);
}
catch (err) {
return this.callbackOrFuture(callback, err, null);
}
}
}
## Building the web API from source
This is not normally necessary for app development, but if you want to do it here are the commands.
cd trac-api/packagegs/web
npm install
npm run tracVersion:windows # For Windows platforms, requires PowerShell
npm run tracVersion:posix # For macOS or Linux
npm run pbjs
npm run pbts # Even if you are using plain JavaScript, this will supply type hints to the IDE