paylike_dart_request 1.0.4
paylike_dart_request: ^1.0.4 copied to clipboard

Low level API client for Paylike

Paylike low-level request helper #

For a higher-level client see https://pub.dev.

This is a low-level library used for making HTTP(s) requests to Paylike APIs. It incorporates the conventions described in the Paylike API reference.

It is built to work in any Dart environment (including Flutter) by accepting a io.HttpClient implementation as input. This library utilises io.HttpClient because of its capabilities to abort requests properly if necessary.

This function is usually put behind a retry mechanism. Paylike APIs will expect any client to gracefully handle a rate limiting response and expects them to retry.

A retry mechanism is not included in this package because it is highly specific to the project and is difficult to implement for streaming requests without further context.

Example #

  var requester = PaylikeRequester().setLog((dynamic o) => print(o));
  var opts = RequestOptions.fromClientId('dart-1')
      .setQuery({
        'foo': 'bar',
      })
      .setVersion(1)
      .setData({
        'foo': 'bar',
      });
  requester.request('http://foo', opts).then((response) {
    return response.getBody();
  }).then((body) {
    print(body);
  }).catchError((error) {
    print(error);
  });

PaylikeRequester #

The default class used to initiate a requester instance

var requester = PaylikeRequester();

By default the requester is initiated with the default io.HttpClient as its client and a simple log function:

class PaylikeRequester {
  Function log = (dynamic o) => print(o);
  io.HttpClient client = io.HttpClient();
  ....
}

You change this by using a named constructor:

var requester = PaylikeRequester.withClientAndLog(io.HttpClient(), (dynamic o) => print(o));

request function

Used for executing requests, have the following footprint:

Future<PaylikeResponse> request(String endpoint, RequestOptions? opts)

Consumes an endpoint and RequestOptions then returns PaylikeResponse

RequestOptions #

Describes the different options you can use to construct your request.

Constructors

var opts = RequestOptions.v1() // Creates a version 1 request option

var opts = RequestOptions.fromClientId('your-client-id'); // Creates from your client id

RequestOptions works utilizing a builder pattern:

  var opts = RequestOptions.fromClientId('dart-1')
      .setQuery({
        'foo': 'bar',
      })
      .setVersion(1)
      .setData({
        'foo': 'bar',
      })
      .setTimeout(Duration(seconds: 20));

PaylikeResponse #

Describes the response of your request

var response = await requester.request('http://foo', opts);

var body = await response.getBody(); // String | Returns response body in plain simple string

var reader = await response.getBodyReader(); // Stream<dynamic> | Returns an object stream with the decoded json body

Error handling #

request may throw any of the following error classes as well as any error thrown by the io.HttpClient implementation.

All error classes can be accessed through the package.

Example #


try {
  await requester.request('http://foo', opts);
catch (e) {
  if (e is RateLimitException) {
    // initiate retry
  }
  if (e is ServerErrorException) {
    // unexpected server error
  }
}


try {
  var opts = RequestOptions().setVersion(0);
} catch (e) {
  if (e is VersionException) {
    // version should be a positive integer
  }
}

Error classes #

  • RateLimitException

    May have a retryAfter (Duration) property if sent by the server specifying the minimum delay.

  • TimeoutException

    Comes from dart:async library https://api.dart.dev/be/169657/dart-async/TimeoutException-class.html

  • ServerErrorException

    Has status and headers properties copied from the io.HttpClientResponse

  • PaylikeException

    These errors correspond to status codes from the API reference. They have at least a code and message property, but may also have other useful properties relevant to the specific error code, such as a minimum and maximum for amounts.

0
likes
100
pub points
28%
popularity

Publisher

paylike.io

Low level API client for Paylike

Homepage

Documentation

API reference

License

BSD (LICENSE)

Dependencies

http, sprintf

More

Packages that depend on paylike_dart_request