Docs‎ > ‎Live API Overview‎ > ‎

Node SDK

Our npm package provides a number of useful methods for working with API's generated within API Creator. Getting started is as easy as running this from the command line (terminal window).

Download the package here or  from the command line:

npm install caliveapicreator

And making your first request will only take a few lines of code. Here we are connecting to a sample API which is available as a sandbox for exploring the basics. Run it as follows (this presumes the jetty install):
  1. Open a command window
  2. Create a file (eg, test.js) in your current working directory
  3. Paste in the contents below, and save
  4. Run it by typing
           node test.js
You should then see a list of customers.  Here's the code to enter into test.js:

var apicreator = require('caliveapicreator');

var api = apicreator.connect('http://localhost:8080/rest/default/demo/v1', 'demo_full');

var customers = api.endpoint('customer');
customers.get().then(function (data) {
    console.log(data); //an array of objects from the customers table
});

In addition to running the node commands from a file (test.js), you can enter the commands directly into a Node command line.  Note: you will need to remove the comment, and combine the last 3 lines above into a single line.

API Methods

1 - connect

Initializes the connection to a project API. It returns an instance of the library according to the project defined. Auth Tokens and users are accessible from the Security section.

Syntax:

apicreator.connect(string projectUrl, string username, string password)
or
apicreator.connect(string projectUrl, string authToken)

Examples:

// Connect with API key
var e1 = apicreator.connect('http://localhost:8080/rest/default/demo/v1', 'demo_full');
// Connect with user name/password
var e2 = apicreator.connect('http://localhost:8080/rest/default/demo/v1', 'demo', 'Password1'); //


2 - endpoint

The endpoint fragment refers to the resource, table, view, or procedure defined in API Creator. This method returns an Endpoint Object, which is used to make RESTful requests.

Syntax:

apicreator.endpoint(string endpointFragment)

Example:

var customers = apicreator.endpoint('customer');

3 - setPageSize

A convenience function for defining the default number of objects retrieved in a endpoint.get() request. This filter can be overridden by explicitly defining the page size in endpoint.get(parameters).

Syntax:

apicreator.setPageSize(integer number)

Example:

apicreator.setPageSize(5);


Endpoint Object Methods

1 - get

Returns a promise for a GET request. 

Syntax:

endpoint.get([string urlParams])

Example:

var custPromise = customers.get('sysfilter=less(balance:1000)');
custPromise.then(function (c) { console.log(c); });

Typical output from this last bit of code:

> [ { '@metadata':
  { href: 'https://localhost:8080/APIServer/rest/default/demo/v1/customer/Alpha%20and%20Sons',
    checksum: 'A:e86aea2e0a4e74bf',
    links: [Object] },
  name: 'Alpha and Sons',
  balance: 4484,
  credit_limit: 9000 },
{ '@metadata':
  { href: 'https://localhost:8080/APIServer/rest/default/demo/v1/customer/Argonauts',
    checksum: 'A:f69d919ec09d6d7c',
    links: [Object] },
  name: 'Argonauts',
  balance: 1858,
  credit_limit: 2000 },
etc...

Your filter can include boolean logic, like this:

'sysfilter=less(balance:1000)&sysfilter=less(credit_limit:5000))'

Parameters by request type are described in detail here.

2 - put

Returns a promise for a PUT request. Parameters by request type are described in detail here.

Syntax:

endpoint.put(object data, [object params])

Example:

var custGetPromise = customers.get();
custGetPromise.then(function (customers) {
    //customers is a paginated list of records and the metadata for each
    customers[0].name = "New Name";

    //a customers[0]["@metadata"].href  attribute describes the endpoint for making PUT requests specifically for customers[0]
    var updatedCustomerEndpoint = e1.endpoint(customers[0]["@metadata"].href);
    var custPutPromise = updatedCustomerEndpoint.put(customers[0], {rulessummary: true});
    custPutPromise.then(function (txSummary) {
        console.log(txSummary); //an object which will include a transaction summary and a summary of the rules fired during this request
    });
});

Example Response:

{
  "statusCode": 201,
  "txsummary": [{
      "@metadata": { ... },
      "name": "New Name",
      "balance": 0,
      "credit_limit": 1234
    }],
  "rulessummary": [{
      "type": "LOGIC_RUNNER",
      "entity": "demo:customer",
      "pk": "demo:customer[{name=New Customer 1}]",
      "subtype": "BEGINUPDATE"
    }, 
    {...}]
}

3 - post

Returns a promise for a POST request. Parameters by request type are described in detail here.

Syntax:

endpoint.post(object data, [object params])

Example:

var custPromise = customers.post({ "name":  "New Customer 1", "credit_limit": 1234 }, {rulessummary: true});
custPromise.then(function (txSummary) {
    console.log(txSummary); //an object which will include a transaction summary and a summary of the rules fired during this request
});

Example Resonse:

{
  "statusCode": 200,
  "txsummary": [{
      "@metadata": { ... },
      "name": "New Customer 1",
      "balance": 0,
      "credit_limit": 1234
    }],
  "rulessummary": [{
      "type": "LOGIC_RUNNER",
      "entity": "demo:customer",
      "pk": "demo:customer[{name=New Customer 1}]",
      "subtype": "BEGINUPDATE"
    }, 
    {...}]
}

4 - del

Returns a promise for a DELETE request. Parameters by request type are described in detail here.

Syntax:

endpoint.del(object data, [object params])

Example:

var custGetPromise = customers.get();
custGetPromise.then(function (customers) {
    //customers is an array of customer records
    //the customers[0]["@metadata"].href attribute describes the endpoint for making DELETE requests specifically for customers[0]
    var customerZero = e1.endpoint(customers[0]["@metadata"].href);
    var custDeletePromise = customerZero.put(customers[0], {rulessummary: true});

    custDeletePromise.then(function (txSummary) {
        console.log(txSummary); //an object which will include a transaction summary and a summary of the rules fired during this request
    });
});