Client Libraries

< Back
Tegan Duong
December 12, 2016

We’ll be the first to admit that our libraries needed attention.  In line with some new updates we’re pushing out in the coming weeks, we realized we had to address this issue.  So without further ado… We've updated our Python, Ruby, and Node libraries! I will go into detail and provide examples below but first here is a quick overview of the updates:

  • Restructured classes: The Python and Ruby libraries were rewritten to use classes with method arguments and validations instead of data structures representing JSON. They are built on top of previous endpoint wrappers (Users/Nodes/Trans classes) so you can still use payloads if needed.
  • ‍Error handling: Native errors were added for better error handling.
  • Convenience methods: Convenience methods were included to make common actions or changes easier to carry out.

1. Restructured Classes

One of the advantages of using native classes in the Python and Ruby libraries is the automatic handling of OAuth. This means that you don’t have to manually call the refresh method every 2 hours! This feature is present in all of the client libraries in addition to more test coverage and inline documentation to better understand and test the functionality of the source code.

Now that the libraries have been restructured, the methods and their associated parameters are slightly different. For example, after initialization, client is now passed in as a parameter to some of the User methods like this: User.all(client, options). In the older versions of the libraries, the client object contained instances of the classes that wrapped the API endpoints (Users/Nodes/Trans), which had methods for making API calls and was formatted like this: client.User.*. Now, the client object is passed into User methods as a parameter, then any instances created from the User class has the client information attached. This also applies to instances created from the other classes (Node and Transaction). Look at the samples from the corresponding libraries for more details: PythonRubyNode.

2. Error Handling

An example of a native error used in the Python library is the NotFoundError instead of a 404 JSON response that you have to parse. Error.message and Error.code return the error message and Synapse error code, respectively. Error.response returns the full JSON response. Here is the full list of error codes and their corresponding error messages:‍


       400: BadRequestError,

       401: UnauthorizedError,

       402: RequestDeclinedError,

       403: ForbiddenError,

       404: NotFoundError,

       406: NotAcceptableError,

       409: ConflictError,

       415: UnsupportedMediaTypeError,

       422: UnprocessableEntityError,

       429: TooManyRequestsError,

       500: InternalServerError,

       502: BadGatewayError,

       503: ServiceUnavailableError,

       504: GatewayTimeoutError


3. Convenience Methods

Some convenience methods have been added to the Python and Ruby libraries. Many of these convenience methods are helpful when updating or changing small sections of user information or adding specific document types to a user. For example, some methods from the Python library include User.add_login, User.remove_login, BaseDocument.add_virtual_document, etc. In addition, both the Python and Ruby libraries now allow you to add physical documents using a base64 string, file path, URL, or byte stream. For more details and other methods available, look at the samples from the corresponding library.

Deprecated Methods

In with the new out with the old! Some methods have been deprecated in the Python and Ruby libraries, including those dealing with KYC 1.0 calls for attaching physical or virtual documents, and answering KBA questions. Here is a list of the deprecated methods:

  • ‍add_doc
  • ‍verify
  • ‍attach_file
  • answer_kba


If you have any questions regarding the implementation, please feel free to reach out to us on our discuss page or email

Tegan Duong

Integration Engineer @ Synapse

©Synapse Financial Technologies Inc. 2020