Working with the ServiceTrade API

The ServiceTrade API is a RESTful web service that allows interaction with ServiceTrade's system.

API Documentation

Technical API documentation is not contained in the Help Center. If you want more in-depth documentation, please go to the following link: https://api.servicetrade.com/api/docs

Authentication and Session Management with the ServiceTrade API

If you’re building an integration to ServiceTrade with our REST API, one of the first things you’ll need to know is how to authenticate and manage your session.  This article discusses how you should handle authentication in integration based on your use case’s requirements, and shows some practical examples using the ServiceTrade Node JS SDK.

Please note that these examples are shown for demonstration purposes only, and should not be used for production use cases.

ServiceTrade API connections are session-based

Unlike some other systems’ APIs, which may manage authentication through permanently assigned API tokens, or an authentication scheme such as OAuth2, ServiceTrade’s API is session-based.  This means that, when you communicate with ServiceTrade’s API, you’ll do so in much the same way that a user would – by authenticating as a specific user, performing some actions, and then logging out of that session.

Here’s an example of how you might do this:

const ST = require('servicetrade-nodejs')();

await ST.login('myUsername', 'myPassword');
/* do some stuff */
await ST.logout();

This workflow works well for simple use cases where you only need to connect to ServiceTrade for a limited amount of time, to perform a specific, discrete action, such as an ad-hoc data cleanup script.  However, it doesn’t work as well for situations where you are running many concurrent operations against the ServiceTrade API, such as responding to webhooks or constantly importing new information from another business system.  Which takes us to our second point...

ServiceTrade API connections are subject to concurrency and login frequency limits

ServiceTrade’s API has a soft limit of 100 concurrent sessions for any one user.  You can temporarily exceed that limit, up to a hard cap of 200 sessions, but in general you should attempt to stay well under the 100 concurrent session limit for each user.  If you exceed the hard cap, your open sessions will be pruned until the 100 concurrent session limit is reached, which may have an impact on your workflows.

In addition, ServiceTrade’s API enforces a per-user login frequency limit.  This frequency limit does not have a deterministic hard cap, but is based on a number of factors such as the diversity of IP addresses from which login attempts occur, as well as the raw count of login attempts during any period of time.  If you exceed the login frequency limit, future login attempts may be throttled or denied.

These limits should not affect normal API use, but if you have developed a complex integration that requires a high volume of interactions with ServiceTrade’s API, you should consider them when architecting your integration.

In such a situation, you should create and store a session token, then use that token for each interaction with ServiceTrade’s API, rather than logging in and out for each individual interaction.  For example:

// utility methods for storing/retrieving your session
const storeAuthToken = async ({authToken}) => {
     // save your session token to a database or other permanent storage
};

const retrieveAuthToken = async () => {
     // retrieve your session token from permanent storage
     };

const connectToServicetrade = async () => {
     const stConfig = {
          onSetCookie: storeAuthToken,
          username: 'myUsername',
          password: 'myPassword',
     };

     const authToken = await retrieveAuthToken();
     if (authToken) {
          stConfig.cookie = 'PHPSESSID=' + authToken;
     }
     const ST = require('servicetrade-nodejs')(stConfig);
     if (!authToken) {
          await ST.login();
     }
     return ST;
};


const ST = await connectToServicetrade();
/* do some stuff */
// no need to call logout() here, since we’ll be reusing the session

However, what if the session token that you’re storing/retrieving has been invalidated – if you accidentally exceeded the concurrent session hard cap, for instance?  Your integration should have graceful authentication failure handling, something like this:

// in addition to the other utility methods above...
const purgeAuthToken = async () => {
     // delete your session token from permanent storage
};

const connectToServicetrade = async () => {
     const stConfig = {
          onSetCookie: storeAuthToken,
          onResetCookie: purgeAuthToken,
          username: 'myUsername',
          password: 'myPassword',
     };
     ... etc ...
};

In a real-world scenario, you might add try/catch logic to detect the purged session and retry the request after successfully re-authenticating.

If you use a programming language other than JavaScript, the source code of the ServiceTrade Node JS SDK can provide some hints on how to manage session setup and teardown in your application.

Best Practices

1. Create a dedicated user, with only the necessary permissions, for each API integration that you create.  API-based integrations should not share a username with a real human user.  Non-technician ServiceTrade users are free, so there’s no additional cost to creating API users in your ServiceTrade account.  
2. For simple use cases that require infrequent/non-persistent connections to ServiceTrade, such as one-time, ad hoc scripts: follow the log in → perform actions → log out workflow.  
3. For complex use cases that require an always-on connection to ServiceTrade, such as webhook listeners and integrations with other systems:  Create and re-use a single session, rather than repeatedly logging in and out for each action.