SDK design

Welcome to the aftership-sdk-nodejs wiki!

Folder structure

lib/
 |--- aftership.js
 |--- handler.js
 |--- payload.js
 |--- error/
        |--- error.js
        |--- error_enum.js

Overview

This SDK make use of request.js, to make the aftership API call simplier.

aftership.js is the class to create the core instance and store the config. It has a public function aftership.call(method, path, options, callback). Everytime you call it, it will create a payload, by the payload.js pass to handler.js, which will handle the payload with its retry policy, and return the err/result to the callback.

Function pseudocode

aftership.js

constructor(api_key, options)

1. check error with _errorHandling(api_key, options) method, will throw error if wrong format
2. inject request.js to the instance
3. store the config in the instance, include

• api_key
• endpoint
• proxy
• retry
• rate

4. set the rate limit property to null
5. create Proxy Method

• GET(...)
• POST(...)
• PUT(...)
• DEL(...)

call(method, path, options, callback)

Public instance function for making request

1. options is optional, shift the argument list if options is not defined
2. construct the payload, by Payload() class
3. handle the payload, by Handler.handlePayload()

_errorHandling(api_key, options)

Private instance function for verify the constructer params

1. Throw SDK error if api_key is of incorrect type
2. Throw SDK error if any fields of options is of incorrect type

payload.js

constructor(aftership, method, path, options)

1. check error with _errorHandling(method, path, options) method, will throw error if wrong format
2. construct the request_object, which will be pass to the request.js
3. delete any null or undefined value in the request_object
4. construct the payload with key-value belows:

• request_object: request_object
• retry: options.retry OR aftership.retry
• raw: options.raw OR false

5. Add retry_count = 0 if retry is true
6. return the payload

_errorHandling(method, path, options)

Private instance function for verify the constructer params

1. Throw SDK error if method is of incorrect type
2. Throw SDK error if path is of incorrect type
3. Throw SDK error if any fields of options is of incorrect type

handler.js

handlePayload(aftership, payload, callback)

Public static function for handle the payload

1. Use the aftership.request, call it with payload.request_obejct
2. if request return error

• if it is one of ETIMEDOUT / ECONNRESET / ECONNREFUSED, retry it with Handler._retryRequestError()
• else return error to the callback

3. else, request do return response from API

• update the aftership.rate_limit
• if code == 429, retry it with Handler._retryTooManyRequestError()
• if code >= 500, retry it with Handler._retryApiError()
• if code != 200 or 201, return error to the callback
• else, it is a OK response
  • if raw is true, return the JSON.stringify response
  • else, return the object response

_retryRequestError(aftership, payload, err, callback)

Private static function for retry request error

1. if retry is true && retry_count < 5

• payload.retry_count++
• call Handler.handlePayload() with the same payload after 1 second

2. else, return Request error object to the callback

_retryTooManyRequestError(aftership, payload, body, callback)

Private static function for retry 429 error

1. if aftership.rate is true

• calculate the timeout, with the current time and aftership.rate_limit.reset
• call Handler.handlePayload() with the same payload after timeout second

2. else, return API error object to the callback

_retryApiError(aftership, payload, body, callback)

Private static function for retry API error (>=500)

1. if retry is true && retry_count < 5

• payload.retry_count++
• call Handler.handlePayload() with the same payload after 1 second

2. else, return API error object to the callback