postmen

postmen

Introduction

Node.js SDK for Postmen API. For problems and suggestions please open GitHub issue

Table of Contents

• Installation
  • NPM Installation
• Quick Start
• class Postmen
  • Postmen(api_key, region, config
  • create(path, input, config, callback)
  • get(path, input, config, callback)
  • Proxy methods of GET,POST,PUT,DELETE
  • Chainable Function
• Promise
• Rate Limiter
• Retry Policy
• Examples
  • Full list
  • How to run
  • Navigation table
• Testing
• License

Installation

NPM installation

npm install postmen

Quick Start

In order to get API key refer to the documentation.

'use strict';

const Postmen = require('postmen');
// TODO key of the Postmen instance
let api_key = 'api-key',
// TODO region of the Postmen instance
let region = 'sandbox';

let postmen = Postmen(api_key, region);

// get all labels by using callback
postmen.get('/labels', function (err, result) {
	if (err) {
		console.log(err);
	} else {
		console.log(result);
	}
});

// get all labels by using promise
postmen.get('/labels').then(function (result) {
		console.log(result);
}).catch(function (err) {
    console.log(err);
});

// get all labels by using promise with chainable function
postmen.useApiKey('ANOTHER_API_KEY').setRetry(false).get('/labels').then(function (result) {
    console.log(result);
}).catch(function (err) {
    console.log(err);
});

// get a particular  labels
postmen.get('/rates/put-your-label-id-here', function (err, result) {
	if (err) {
		console.log(err);
	} else {
		console.log(result);
	}
});

class Postmen

Postmen(api_key, region, config)

Initiate Postmen SDK object. In order to get API key and choose a region refer to the documentation.

Argument	Required	Type	Default	Description
api_key	YES	string	N/A	API key
region	YES	string	N/A	API region (sandbox, production)
config	NO	object	null	Options
config['endpoint']	—	string	null	Custom URL API endpoint
config['retry']	—	boolean	true	override default retry if set, see Retry policy
config['rate']	—	boolean	true	Wait before API call if rate limit exceeded or retry on 429 error
config['raw']	—	boolean	false	To return API response as a raw string
config['proxy']	—	string	null	Proxy credentials

create(path, input, config, callback)

Creates postmen api object

Argument	Required	Type	Default	Description
path	YES	string	N/A	start with /, see available path here key
input	YES	object	null	object of request config
input['body']	YES	string	null	POST body
input['query']	NO	object	null	query object
config	NO	object	null	object of request config
config['retry']	NO	boolean	true	override default retry if set, see Retry policy
config['raw']	NO	boolean	false	if true, return result as string, else return as object
callback	NO	function	N/A	the callback to handle error and result, the result is the response body of the request

API Docs:

• POST /rates
• POST /labels
• POST /manifests
• POST /cancel-labels
• POST /address-validations

Examples:

• rates_create.js
• labels_create.js
• manifests_create.js
• cancel_labels_create.js
• address_validation_create.js

get(path, input, config,callback)

Get Postmen API objects (list or a single objects).

Argument	Required	Type	Default	Description
path	YES	string	N/A	start with /, see available path here key
input	NO	object	null	object of request config
input['body']	NO	string	null	POST body
input['query']	NO	object	null	query object or string
config	NO	object	null	object of request config
config['retry']	NO	boolean	true	override default retry if set, see Retry policy
config['raw']	NO	boolean	false	if true, return result as string, else return as object
callback	NO	function	N/A	the callback to handle error and result, the result is the response body of the request

postmen.get( '/path/label-id', callback);
// is equivalent to
postmen.call('GET', '/path/label-id', input, config, callback);

postmen.get( '/path', input, config, callback);
// is equivalent to
postmen.call('GET', '/path', input, config, callback);

API Docs:

• GET /rates
• GET /rates/:id
• GET /labels
• GET /labels/:id
• GET /manifests
• GET /manifests/:id
• GET /cancel-labels
• GET /cancel-labels/:id

Examples:

• rates_retrieve.js
• labels_retrieve.js
• manifests_retrieve.js
• cancel_labels_retrieve.js

Proxy Method (GET, POST, PUT, DELETE)

There are also interface GET, POST, PUT, DELETE which are proxy to Postmen.call(...)

postmen.call('GET', '/path', input, config, callback);
// is equivalent to
postmen.GET('/path', input, config, callback);

// So as `POST`, `PUT` and `DELETE`

Chainable Function

Using chainable function to config now is accepted. Now postmen instance has these chainable function:

• useApiKey() temporarily use an api_key to make request
• setProxy() overwrite postmen proxy property
• setRetry() overwrite postmen retry property
• setRaw() overwrite postmen raw property

postmen.useApiKey('ANOTHER_API_KEY').get('labels').then();
// is equivalent to
let input = {};
let config = {
	api_key: 'ANOTHER_API_KEY'
}
postmen.get('labels', input, config).then();

Promise:

Only create(path, config, callback) and get(path, config, callback) function support promise.

• create example
• get example.

Rate Limiter:

To understand Postmen rate limit policy, please see limit session in https://docs.postmen.com/ratelimit.html

You can get the recent rate limit by postmen.rate_limit. Initially all value is {}.

let postmen = Postmen('YOUR_API_KEY', 'region');
console.log(postmen.rate_limit);

// console output
// {}

After making an API call, it will be set.

postmen.get('/labels', function (err, result) {
	console.log(postmen.rate_limit);
});

// console output
// { 'YOUR_API-KEY' : { limit: 600, remaining: 599, reset: 1453281417 } }

When the API response with 429 Too Many request error

• if rate is true, it wont throw, will delay the job, retry when the rate limit is reset.
• if rate is false, it will return 429 Too Many request error to the callback

Retry policy

If API error is retryable, SDK will wait for delay and retry. Delay starts from 1 second. After each try, delay time is doubled. Maximum number of attempts is 5.

You can set the retry flag

• in constructor as default retry flag
• specify in config of get() or create() method

Examples

Full list

All examples avalible listed in the table below.

File	Description
rates_create.js	rates object creation
rates_retrieve.js	rates object(s) retrieve
labels_create.js	labels object creation
labels_retrieve.js	labels object(s) retrieve
manifests_create.js	manifests object creation
manifests_retrieve.js	manifests object(s) retrieve
cancel_labels_create.js	cancel-labels object creation
cancel_labels_retrieve.js	cancel-labels object(s) retrieve
address_validation_create.js	address_validation object(s) creation
proxy.js	Proxy usage
error.js	Avalible ways to catch/get errors
response.js	Avalible output types

How to run

Download the source code, go to examples directory.

Put your API key and region to credentials.js

Check the file you want to run before run. Some require you to set additional variables.

Navigation table

For each API method SDK provides Node.js wrapper. Use the table below to find SDK method and example that match your need.

Model \ Action	create	get all	get by id
rates	.create('/rates', input, config, callback)	.get('/rates', input, config, callback)	.get('rates/rate-id-here', input, config, callback)
labels	.create('/labels', input, config, callback)	.get('/labels', input, config, callback))	.get('/labels/label-id-here', input, config, callback))
manifest	.create('/manifest', input, config, callback)	.get('/manifest', input, config, callback)	.get('/manifest/manifest-id-here', input, config, callback)
cancel-labels	.create('/cancel-labels', input, config, callback)	.get('/cancel-labels', input, config, callback)	.get('/cancel-labels/cancel-labels-id-here', input, config, callback)
address-validations	.create('/address-validations', input, config, callback)

Testing

mocha --recursive

License

Released under the MIT license. See the LICENSE file for details.

Changelog

[2.0.0] - 2023-03-09

Breaking Changes

• Legacy API key is now deprecated and cannot be used for authentication. Please use this guide to obtain a modern API key for making requests with this version.

This update does not require any changes to your code base. However the legacy Postmen API key cannot be used anymore.

You can check which version of API keys you are using by looking at the header key used for authentication:

Type | API Header Key --- | --- Legacy API Key | postmen-api-key Modern API Key | as-api-key