ianfortier/basic-freshsales-api

A basic REST Freshsales API wrapper.

dev-master 2020-05-05 02:17 UTC

Requires

• php: >=7.1.0
• guzzlehttp/guzzle: ^6.3
• guzzlehttp/promises: ^1.3
• psr/log: ^1.1

MIT

• Ian Fortier

• rest
• api
• freshsales

README

A simple API wrapper for Freshsales using Guzzle. It supports both the REST API provided by Freshsales, and basic rate limiting abilities. Also supported: asynchronous requests through Guzzle's promises.

This library required PHP >= 7.

PS: This project is largely inspired (aka copy <3 ) from osiset/Basic-Shopify-API.

Table of Contents

• Installation
• Usage * REST (sync) * REST (async)
  • Making requests * If sync is true (regular rest call): * If sync is false (restAsync call):
  • Checking API limits
  • Rate Limiting
    • Enable Rate Limiting
    • Disabiling Rate Limiting
    • Checking Rate Limiting Status
    • Getting Timestamps
  • Errors
  • Logging
• Documentation
• LICENSE

Installation

The recommended way to install is through composer.

composer require ianfortier/basic-freshsales-api

Usage

Add use ianfortier\BasicFreshsalesAPI; to your imports.

REST (sync)

For REST calls, the shop domain and access token are required.

$api = new BasicFreshsaleAPI();

// Now run your requests...
$resul = $api->rest(...);

REST (async)

For REST calls, the shop domain and access token are required.

$api = new BasicFreshsaleAPI();

// Now run your requests...
$promise = $api->restAsync(...);
$promise->then(function ($result) {
  // ...
});

Making requests

REST

Requests are made using Guzzle.

$api->rest(string $type, string $path, array $params = null, array $headers = [], bool $sync = true);

• type refers to GET, POST, PUT, DELETE, etc
• path refers to the API path, example: /api/leads
• params refers to an array of params you wish to pass to the path, examples: ['email' => '[e-mail]']
• headers refers to an array of custom headers you would like to optionally send with the request, example: ['X-Freshsales-Test' => '123']
• sync refers to if the request should be synchronous or asynchronous.

You can use the alias restAsync to skip setting sync to false.

If sync is true (regular rest call):

The return value for the request will be an object containing:

• response the full Guzzle response object
• body the JSON decoded response body (array)
• bodyObject the JSON decoded response body (stdClass)

Note: request() will alias to rest() as well.

If sync is false (restAsync call):

The return value for the request will be a Guzzle promise which you can handle on your own.

The return value for the promise will be an object containing:

• response the full Guzzle response object
• body the JSON decoded response body (array)
• bodyObject the JSON decoded response body (stdClass)

$promise = $api->restAsync(...);
$promise->then(function ($result) {
  // `response` and `body` available in `$result`.
});

Passing additional request options

If you'd like to pass additional request options to the Guzzle client created, pass them as the second argument of the constructor.

$api = BasicFreshsaleAPI(true, ['connect_timeout' => 3.0]);

In the above, the array in the second argument will be merged into the Guzzle client created.

Checking API limits

After each request is made, the API call limits are updated. To access them, simply use:

// Returns an array of left, made, and limit.
// Example: ['left' => 79, 'made' => 1, 'limit' => 80]
$limits = $api->getApiCalls('rest');

Rate Limiting

This library comes with a built-in basic rate limiter, disabled by default. It will sleep for x microseconds to ensure you do not go over the limit for calls with Freshsales.

By default the cycle is set to 500ms, with a buffer for safety of 100ms added on.

Enable Rate Limiting

Setup your API instance as normal, with an added:

$api->enableRateLimiting();

This will turn on rate limiting with the default 500ms cycle and 100ms buffer. To change this, do the following:

$api->enableRateLimiting(0.25 * 1000, 0);

This will set the cycle to 250ms and 0ms buffer.

Disabiling Rate Limiting

If you've previously enabled it, you simply need to run:

$api->disableRateLimiting();

Checking Rate Limiting Status

$api->isRateLimitingEnabled();

Errors

This library internally catches only 400-500 status range errors through Guzzle. You're able to check for an error of this type and get its response status code and body.

$call = $api->rest('GET', '/xxxx/non-existant-route-or-object');

if ($call->errors) {
  echo "Oops! {$call->status} error";
  var_dump($call->body);

  // Original exception can be accessed via `$call->exception`
  // Example, if response body was `{"error": "Not found"}`...
  /// then: `$call->body` would return "Not Found"
}

Logging

This library accepts a PSR-compatible logger.

$api->setLogger(... your logger instance ...);

LICENSE

This project is released under the MIT license.