Methods

This document details the methods of the JavaScript client library.

Initializing the client

Begin by initializing an instance of DeskproClient, from the @deskpro/deskpro-api-client-javascript package, with the URL to your Deskpro instance.

const DeskproClient = require('@deskpro/deskpro-api-client-javascript');

const client = new DeskproClient('http://deskpro.company.com');

Axios is used to make HTTP requests. A default Axios client will be used by the library, but a custom instance may be provided.

const DeskproClient = require('@deskpro/deskpro-api-client-javascript');

const httpClient = axios.create({
  timeout: 1000
});
const client = new DeskproClient('http://deskpro.company.com', httpClient);

// Or use the setter method.
// client.setHTTPClient(httpClient);

Requests may be logged by passing a function as the third constructor argument.

const DeskproClient = require('@deskpro/deskpro-api-client-javascript');

const logger = console.log;
const client = new DeskproClient('http://deskpro.company.com', null, logger);

// Or use the setter method.
// client.setLogger(logger);

Authenticating

Many API methods require authentication. Set the ID of the user to authenticate with and either the auth "key" or "token".

const DeskproClient = require('@deskpro/deskpro-api-client-javascript');

const client = new DeskproClient('http://deskpro.company.com');

// Use the setAuthKey method to authenticate using a key.
const personId = 1;
const authKey  = 'dev-admin-code';
client.setAuthKey(personId, authKey);

// Use the setAuthToken method to authenticate using a token.
personId  = 1;
authToken = 'AWJ2BQ7WG589PQ6S862TCGY4';
client.setAuthToken(personId, authToken);

Get

Sends a GET request to the API.

DeskproClient::get(endpoint, params = {}) : Promise

const DeskproClient = require('@deskpro/deskpro-api-client-javascript');

const client = new DeskproClient('http://deskpro.company.com');
client.setAuthKey(1, 'dev-admin-code');

client.get('/articles')
  .then((resp) => {
    console.log(resp.data);
  })
  .catch((err) => {
    console.error(err.message);
  });

// Parameters are interpolated into the provided URL.
// The next request will be made to "/articles/101?limit=25".
const params = {
  id:    101,
  limit: 25
};
client.get('/articles/{id}', params);

Post

Sends a POST request to the API.

DeskproClient::post(endpoint, body = null, params = {}) : Promise

const DeskproClient = require('@deskpro/deskpro-api-client-javascript');

const client = new DeskproClient('http://deskpro.company.com');
client.setAuthKey(1, 'dev-admin-code');

const body = {
  title:   'Mary Had a Little Lamb',
  content: 'Whose fleece was white as snow.'
};

client.post('/articles', body)
  .then((resp) => {
    console.log(resp.data);
  })
  .catch((err) => {
    console.error(err.message);
  });

Put

Sends a PUT request to the API.

DeskproClient::put(endpoint, body = null, params = {}) : Promise

const DeskproClient = require('@deskpro/deskpro-api-client-javascript');

const client = new DeskproClient('http://deskpro.company.com');
client.setAuthKey(1, 'dev-admin-code');

const body = {
  title:   'Mary Had a Little Lamb',
  content: 'Whose fleece was white as snow.'
};
const params = {
  id: 101
};

client.put('/articles/{id}', body, params)
  .then((resp) => {
    console.log(resp.data);
  })
  .catch((err) => {
    console.error(err.message);
  });

Delete

Sends a DELETE request to the API.

DeskproClient::del(endpoint, params = {}) : Promise

const DeskproClient = require('@deskpro/deskpro-api-client-javascript');

const client = new DeskproClient('http://deskpro.company.com');
client.setAuthKey(1, 'dev-admin-code');

const params = {
  id: 101
};
client.del('/articles/{id}', params)
  .then((resp) => {
    console.log(resp.data);
  })
  .catch((err) => {
    console.error(err.message);
  });

Batch

Sends a batch request to the API.

DeskproClient::batch(requests) : Promise

const DeskproClient = require('@deskpro/deskpro-api-client-javascript');

const client = new DeskproClient('http://deskpro.company.com');
client.setAuthKey(1, 'dev-admin-code');

client.batch({
  one: {
    method: 'GET',
    url: '/articles/105'
  },
  two: '/articles/106'
}).then((resp) => {
  console.log(resp.one.data);
  console.log(resp.two.data);
}).catch((err) => {
  console.error(err.message);
});

Request

Sends a request to the API.

DeskproClient::request(method, endpoint, body = null, params = {}, headers = {}) : Promise

const DeskproClient = require('@deskpro/deskpro-api-client-javascript');

const client = new DeskproClient('http://deskpro.company.com');
client.setAuthKey(1, 'dev-admin-code');

const body = {
  title:   'Mary Had a Little Lamb',
  content: 'Whose fleece was white as snow.'
};
const params = {
  id: 101
};
const headers = {
  'X-Custom-Value': 'some value'
}
client.request('PUT', '/articles/{id}', body, params, headers)
  .then((resp) => {
    console.log(resp.data);
  })
  .catch((err) => {
    console.error(err.message);
  });

Default Headers

Sets the headers sent with each request.

DeskproClient::setDefaultHeaders(defaultHeaders) : DeskproClient

const DeskproClient = require('@deskpro/deskpro-api-client-javascript');

const client = new DeskproClient('http://deskpro.company.com');
client.setAuthKey(1, 'dev-admin-code');

// Send these headers and values with each request made to the API.
client.setDefaultHeaders({
  'X-Custom-Value': 'some value'
});

Response

Each of the methods get, post, put, delete, batch, and request returns an object with the properties data, meta, and linked.

const DeskproClient = require('@deskpro/deskpro-api-client-javascript');

const client = new DeskproClient('http://deskpro.company.com');
client.setAuthKey(1, 'dev-admin-code');

client.get('/articles')
  .then((resp) => {
    console.log(resp.data);
    console.log(resp.meta);
    console.log(resp.linked);
  });

Browser Usage

The client library may be used in the browser as well as Node. The library may be installed using npm or embedded in a document using the unpkg.com CDN.

<!DOCTYPE>
<html>
  <head>
    <!-- Import DeskproClient from node_modules -->
    <script src="node_modules/@deskpro/deskpro-api-client-javascript/dist/index.js"></script>

    <!-- Or import it from CDN -->
    <!-- <script src="https://unpkg.com/@deskpro/deskpro-api-client-javascript@2.0.0/dist/index.js"></script> -->
  </head>
  <body>
    <script>
      var client = new DeskproClient('http://deskpro.company.com');
      client.setAuthKey(1, 'dev-admin-code');

      client.get('/articles')
          .then(function(resp) {
            console.log(resp.data);
          })
          .catch(function(err) {
            console.error(err.message);
          });
    </script>
  </body>
</html>