Forem: Andrew McIntosh

API Client Design Across Languages - Part 2 - Making Requests

Andrew McIntosh — Tue, 29 Mar 2022 18:53:59 +0000

It's been a while since my last post (API Client Design Across Languages - Part 1), but life and work have gotten in the way. Regardless, I'm am finally continuing my dive into how API clients can differ in style and usage across languages while still maintaining the same features.

The first post focused on the basic structure of different API clients. In this post I will go into how a client may make requests against the API.

Request Libraries

Languages vary in how well supported making HTTP requests is in their core implementations or standard libraries. Almost by definition, languages used on the web generally have easy ways to make HTTP requests. However, there are often dedicated request libraries that can make this simpler or cleaner, and in general I recommend their use unless the language has very clear and clean support.

There are reasons to not want to include a request library in an SDK as every additional dependency added is one that developers using it will have to add as well. Keeping a small dependency graph also makes it easier to maintain updates. But, letting a library do the low-level work is also good for maintenance and security, and often someone looking to use your SDK will already be using a request library.

I'll show some examples of the choices FreshBooks made for different languages below.

Sane Request Defaults

Both to make it easier for developers to use our SDKs, and to make our own lives easier in supporting them, we set some defaults for HTTP requests.

Timeouts are especially important. If a request takes too long, it may can impact both the user (slowing the response to their customer) and us (if our servers get saturated by slow requests, we stop service our customers). Most HTTP clients have easily set timeouts but often they are not enabled by default.

Setting user-agent strings is also helpful. Including things like the SDK language and version helps FreshBooks figure our SDK usage and what languages are popular with our developers. Of course we let users over-ride the user-agent if desired. It can also help an API support team track down a reported error if the client has a unique user-agent string.

Interface

The SDK should try to be as consistent and intuitive as possible, especially if the API itself is a fairly CRUD-heavy RESTful API versus one with more unique behaviours around resources.

Try to make to keep things standardized like resorce pluralization (eg. clients, invoices vs. client, invoices).

Try to keep method signature variables in a similar order. For instance:

clients.get(id, filters)
clients.create(data, filters)
clients.update(id, data, filters)

versus

invoices.get(id, filters)
invoices.create(data)
invoices.update(data, id, filters)

The more standard and intuitive the SDK is, the easier it is for developers and the fewer support tickets.

FreshBook's SDKs

Like last time, I'll show some examples of how FreshBook's SDKs are built in a few different languages.

Python

In python we're using the requests library for simplicity. Requests is widely used (see the Stripe and Auth0 SDKs) so it isn't too onerous of a requirement. In fact, FreshBooks' Python SDK is very light on dependencies in general.

You can see where we instantiate a session (to allow for retries), and make the HTTP requests). In the client we can instantiate the shared client code for each different resource.

Usage looks like:

invoice = freshBooksClient.invoices.get(account_id, invoice_id)
clients = freshBooksClient.clients.list(account_id)

assert clients[0].organization == "FreshBooks"

Node.js

Like Python, our Node.js SDK is using a well-known library axios. While it is not quite as ubiquitous as Python's requests, it is very commonly used. For instance, it is used by Auth0 (if you're looking for a different example, Shopify makes use of Got). You can find it configured here. The shared client code takes reqeust and response transform functions for each resource to convert the repsonses to objects.

PHP

Like Node.js, the PHP ecosystem has quite a number of good HTTP request libraries. Guzzle is perhaps one of the most well known, but there are many other popular libraries out there. Luckily, PHP also has some interface standards around HTTP clients and messages, particularly PSR-7, PSR-17, and PSR-18,

Implementing the FreshBooks SDK to these standards means that we don't force any particular library on developers. They are free to choose any library that implements those standards.

In our README we provide an example for those who have no particular preference:

Requires a PSR-18 implementation client. If you do not already have a compatible client, you can install one with it.

composer require amcintosh/freshbooks php-http/guzzle7-adapter

Again, here is the configuration, and the resources using shared client code.

Usage looks like:

$invoice = $freshBooksClient->invoices()->get($accountId, $invoiceId);
$clients = $freshBooksClient->clients()->list($accountId);

echo $clients->clients[0]->organization; // 'FreshBooks'

Up Next

So there you can see a number of different HTTP client options, and examples of how FreshBooks' SDKs utilize them.

I hope you found something interesting or useful here and I hope you can catch the next post where I plan to go into request data and response structures.

API Client Design Across Languages - Part 1

Andrew McIntosh — Thu, 11 Nov 2021 17:39:03 +0000

In my recent post Some Best Practices On Building An Integration, I espoused the benefits of using API owner supplied tools and libraries, and mentioned areas where a well-built SDK hides complexity from, or otherwise makes things easier for, a developer.

A colleague suggested that it might be useful to present examples of some of these areas to give some pointers for someone who needs to implement that functionality themselves, can't make use of an SDK, or simply for someone looking to build their own API client. So, this is part 1 of a deep dive into functionality in FreshBooks' (and some other API owner's) SDKs.

Basic Structure

This first post won't go too much into functionality as I think it's best to start on structure.

A RESTful API is language agnostic and clients built any number of languages must all support the same API features and resources. However, the actual design of the client and usage of the client itself can, and probably should, be different language to language. For example, a Ruby client versus a Java client will still call the same API endpoint, but the form of the methods to make that call, and the form of the returned data could look very different.

I feel it's best to build an API client in a way that is natural to the specific language it's written in. This extends from the project layout, to the client initialization, the method calls themselves, and the returned data. This makes things more intuitive and easy for a developer to use.

The language influences the design primarily in two ways: language capabilities, and common language conventions.

Capabilities

By capabilities, I'm talking about language design and features. A statically typed language usually needs a bit more structure than a dynamically typed one. For instance, an API client in a language like PHP or Python could return JSON results as associative arrays (array and dictionary respectively), as you don't have to declare the various return value's types are. It would be difficult to do the same in Java with a HashMap (possible, but it would not be clean), so you're much more likely to build data objects for the responses with all the fields included and nicely typed.

Other features play in as well. How does the language handle functions with different options? Function overloadings? Optional arguments? These all affect the design.

Conventions

Beyond what you can do with a language, there's also what you should do. You can write your Python or Ruby in a very Java-like way, but it might not feel as natural to a Ruby developer using your library. Of course conventions aren't so cut-and-dry as capabilities; there are many ways to do something and sometimes one is considered "more right" than others, but often not as well. Looking at how other libraries are implemented and getting to know a language helps informs a lot of design choices. The best advice is to try to make things clear.

FreshBook's SDKs

At the time of writing, FreshBooks has first-party Python and Node.js SDKs, and a community-supported Java one (all three are listed here). As I said, I'm going to walk through some of the differences in the design, but today I'll get started with the basics of client initialization and configuration.

First, let's talk about the configuration the FreshBooks' SDKs need to support:

We require the clients to be initialized with their application's unique client id for the user-agent string, so that's a required parameter.
To use the API requires authentication. Depending on what a developer has implemented, they'll either have a valid OAuth2 access token to initialize the client with, or they'll want to go through the authorization flow, which would require their client secret and redirect urls. Ideally the SDK supports both.
If they have an expired token, they may want to refresh it, which would require the refresh token to be supplied.
The developer may want to override some of the default settings like user-agent string, timeouts, or disabling automatic retries on failures.

Java

I'll start with the Java SDK because the features of the Java language makes it a good first example to set the others against.

Java supports function overloading, but with the number of possible options mentioned above, that would get very compicated combination-wise. You could just use nullable parameters, but that would be confusing and ugly. For example:

public FreshBooksClient(
    String clientId, String clientSecret, String redirectUri,
    String accessToken, String userAgent, Integer timeout
) {
    ...

which could like anything like:

client = new FreshBooksClient(
    <client_id>, <client_secret>, <url>, null, null, null);
client = new FreshBooksClient(
    <client_id>, null, null, <access_token>, null);
client = new FreshBooksClient(
    <client_id>, null, null, <access_token>, null, 30);

This is what the builder pattern is for. You can see the full code for
the client and the builder on github but essentially the client is not initialized directly. You initialize a "client builder", which has a constructor for each of the base cases ("client_id" versus "client_id, secret, url") and different methods for the various options, and the builder returns a client.

private FreshBooksClient(FreshBooksClientBuilder builder) {
    ...
}

public FreshBooksClientBuilder(
    String clientId, 
    String clientSecret, 
    String redirectUri
) {
    ...
}

public FreshBooksClientBuilder(String clientId) {
    ...
}

public FreshBooksClientBuilder withAccessToken(
    String accessToken
) {
    ...
}

public FreshBooksClientBuilder withReadTimeout(
    int timeout
) {
    ...
}

Which allows you to instantiate the client in the various differing ways cleanly:

client = new FreshBooksClient.FreshBooksClientBuilder(
        <client_id>, <client_secret>, <url>)
    .build();
client = new FreshBooksClient.FreshBooksClientBuilder(
        <client_id>)
    .withAccessToken(<valid token>)
    .build();
client = new FreshBooksClient.FreshBooksClientBuilder(
        <client_id>)
    .withAccessToken(<valid token>)
    .withReadTimeout(30)
    .build();

This requires much more structure in the client, but allows much cleaner usage.

Python

By comparison, Python allows for a much more concise implementation. Python is an object-oriented language and you could implement a builder pattern, but as python also supports named parameters, and there actually aren't too many options for the client, we can get away with something much simpler and more in the pythonic style (again, full code on github).

def __init__(
    self, 
    client_id: str, 
    client_secret: Optional[str] = None, 
    redirect_uri: Optional[str] = None,
    access_token: Optional[str] = None, 
    refresh_token: Optional[str] = None,
    user_agent: Optional[str] = None, 
    timeout: Optional[int] = DEFAULT_TIMEOUT,
    auto_retry: bool = True
):

which allows for:

client = Client(
    <client_id>, 
    client_secret=<client_secret>, 
    redirect_uri=<url>
)
client = Client(
    <client_id>, 
    access_token=<valid token>
)
client = Client(
    <client_id>, 
    access_token=<valid token>, 
    timeout=30
)

As you can see, the language features of Python can lead to a very different implementation and usage than Java.

Node.js

FreshBooks' Node.js SDK is written in TypeScript. Again, there are different ways to go about implementation, but we took a fairly common javascript pattern and passed a configuration object as a parameter. The Stripe Node.js Library does something similar (in general Stripe is a great place to look for any "how have others"-type API questions.)

export interface Options {
    clientSecret?: string
    redirectUri?: string
    accessToken?: string
    refreshToken?: string
    apiUrl?: string
    retryOptions?: IAxiosRetryConfig
    userAgent?: string
}

constructor(clientId: string, options: Options = {}) {
    const defaultRetry = {
        retries: 10,
        retryDelay: axiosRetry.exponentialDelay,
        retryCondition: APIClient.isNetworkRateLimitOrIdempotentRequestError,
    }
    const {
        clientSecret,
        redirectUri,
        accessToken,
        refreshToken,
        apiUrl = process.env.FRESHBOOKS_API_URL || API_BASE_URL,
        retryOptions = defaultRetry,
    } = options

with initialization looking like:

client = new Client(<client_id>, {
    clientSecret: <client_secret>
    redirectUri:  <url>
})

client = new Client(<client_id>, {
    accessToken: <valid token>,
})

This also happens to be a fairly common pattern in PHP, thus a possible future FreshBooks PHP SDK would likely look similar. auth0's PHP SDK has an example of this.

Up Next

I hope you found it interesting seeing the different ways a client for the same API can look language-to-language. As I said, I'll dive a bit more into functionality differences next time, but feel free to dig around the projects and if you have any questions, please reach out.

Advent of Code

Andrew McIntosh — Thu, 04 Nov 2021 02:41:50 +0000

Hacktoberfest is done, but the Advent of Code is less than a month away.

Anyone planning to participate?
What language do you want to use?

My First Hacktoberfest As A Maintainer

Andrew McIntosh — Fri, 29 Oct 2021 23:31:29 +0000

I've been participating in Hacktoberfest for a few year now and it's always been a fun and interesting experience looking for projects I can lend a hand on.

This year however I happened to have a few public projects myself, one of my own and a few through work that I'm a maintainer of, so I figured I might as well open them up to Hacktoberfest contributions and see if there was any interest. I wasn't expecting much, but I was taken by surprise!

I've had public repos in past years, but never something really of interest to a wider audiance or with clear enough needs and defined work.

So the first thing I did was get a few github issues together for each. The work projects already had some, but I tidied them up and pull a few more from our internal bug tracker. For my own project I went though my local todo list and made issues for them. Finally I labelled the issues and the projects with the "hacktoberfest" tag, and marked a few more straight forward ones as "good first issues".

And then I went about my life. One morning however I saw a message about a pull request against the one repo. Someone had come along and was contributing! I reviewed the work, which was good (and actually improved some existing work), thanked them, and merged. The next morning there was another from the same developer! This issue had some ambiguity so we chatted about the work and before long they came back with changes and it too was merged. I was thrilled as these two issues were things that I had been meaning to get to for a bit, but hadn't had a chance.

I was even more surprised a few weeks later when someone opened a pull request against the one project with a minor refactor that improved the "pythonic" style of it. There was no issue around it, someone had just read through the code and saw a way it could be better. I don't know for sure that this developer came in via the hacktoberfest, but I suspect they may have.

So for me, this hacktoberfest helped me cross off a bunch of work from my todo, helped me clarified some of the work that when I documented the issues and agian when I discuss them with the other developer, and showed me some improvements that I hadn't even thought of. Overall a great experience.

Python API Client Using Magic Methods

Andrew McIntosh — Fri, 29 Oct 2021 11:30:09 +0000

Python "magic methods" allow for some very fun and powerful code.

Magic methods refers to all those special methods in Python classes that start and end with __.

The documentation for Special method names says:

A class can implement certain operations that are invoked by special syntax (such as arithmetic operations or subscripting and slicing) by defining methods with special names.

For instance the __init__ method is called when a new instance of a class is instantiated. __str__ is a method that returns a string representation of the class. As stated in the docs, these are not methods that generally get invoked directly on the class. For example, you don't call my_object.__str__() but __str__ would be called by print(my_object).

In this post, I'm going to demonstrate using the __getattr__ and __call__ magic methods to build a dynamic API client.

Let's say you're building a client for an API with endpoints like:

GET https://some-api.net/user
GET https://some-api.net/user/permissions
POST https://some-api.net/article
GET https://some-api.net/article/

There are a lot of ways to build a client for this. One might look like:

import logging
import requests

class APIClient:
    BASE_URL = "https://some-api.net"

    def make_request(method, url, params=None, data=None):
        response = requests.request(
            method,
            f"{self.BASE_URL}/{url}"
            params=params,
            json=data
        )

        response_body = {}
        try:
            response_body = response.json()
        except ValueError:
            log.warning("Unexpected Response '%s' from '%s'",
                        response.content, response.url)
        return response_body

    def get_user(self):
        return self.make_request("GET", "user")

    def get_user_permissions(self):
        return self.make_request("GET", "user/permissions")

    def create_article(self, data):
        return self.make_request("POST", "article", data=data)

    def get_article(self, id):
        return self.make_request("GET", f"article/{id}")

We would then use the client:

client = APIClient()

user = client.get_user()
permissions = client.get_user_permissions()
new_article = client.create_article({"some": "data"})
existing_article = client.get_article(123)

And this is fine.

But what if the API is changing often? Or if there are dozens of endpoints and you don't know which you need to call? If later on you discover you need to call GET https://some-api.net/user/roles or GET https://some-api.net/some_other_thing?some_param=foo, you'll need to go back to you client and add matching methods.

It would be nice to have things a bit more dynamic, and one way to do that is with magic methods. Specifically, I'll be using:

__getattr__ which is "Called when the default attribute access fails with an AttributeError" (see the docs). This means that if you call my_object.some_missing_attr, then __getattr__ will get invoked with "some_missing_attr" as the name parameter.
__call__ which is "Called when the instance is "called" as a function" (see the docs), eg. my_object()

Using these, we can build something like:

import logging
import requests

log = logging.getLogger(__name__)

class APIClient:
    BASE_URL = "https://some-api.net"

    def __init__(self, base_url=None):
        self.base_url = base_url or BASE_URL

    def __getattr__(self, name):
        return APIClient(self._endpoint(name))

    def _endpoint(self, endpoint=None):
        if endpoint is None:
            return self.base_url
        return "/".join([self.base_url, endpoint])

    def __call__(self, *args, **kwargs):
        method = kwargs.pop("method", "GET")

        object_id = kwargs.pop("id"))
        data = kwargs.pop("data", None)

        response = requests.request(
            method,
            self._endpoint(object_id),
            params=kwargs,
            json=data
        )

        response_body = {}
        try:
            response_body = response.json()
        except ValueError:
            log.warning("Unexpected Response '%s' from '%s'",
                        response.content, response.url)
        return response_body

This allows us to call the API like so:

client = APIClient()

user = client.user()
permissions = client.user.permissions()
new_article = client.article(method="POST", data={"some": "data"})
existing_article = client.article(id=123)

How does this work?

Well in the case of client.user.permissions(), .user is an attribute and since the client doesn't have that attribute, it calls __getattr__ with name="user", which then returns an APIClient instance with the name appended to the endpoint URL. The same happens when .permissions is invoked on the APIClient instance that was returned by .user, in turn giving us another APIClient instance, now with a path of https://some-api.net/user/permissions. Finally this APIClient instance is called by (), which invokes the __call__ method. This method makes the actually HTTP call to the constructed URL based in any parameteres passed in, but defaults to a GET request.

In the case of the article calls, client.article(id=123) works much the same way, but the APIClient is called with an id parameter. This id gets appended to the url by the same internal _endpoint() method that __getattr__ uses, which results in a GET call to https://some-api.net/article/<id>.

For client.article(method="POST", data={"some": "data"}), we override the method and add a data payload to the POST.

As you can see, the client itself can handle a large variety of API calls without any significant changes, allowing the utilizing application a lot of flexibility.

In the example of the newly required calls, GET https://some-api.net/user/roles and GET https://some-api.net/some_other_thing?some_param=foo, no changes to the client are needed:

roles = client.user.roles()
thing = client.some_other_things(some_param="foo")

Some Best Practices On Building An Integration

Andrew McIntosh — Tue, 19 Oct 2021 10:57:35 +0000

Hi, I’m Andrew McIntosh. I’m a software engineer at FreshBooks. I’ve moved around development teams a couple of times, but right now I’m working on our API and Integrations team, trying to make things better for developers looking to build API integrations. If that’s you, or you want that to be you, here are five bits of advice on how you can build an (or build a better) API integration:

Get To Know The API
Use Libraries, Tools, and SDKs
Limit The Scope of Requests
Properly Handle Errors
Do More Asynchronous Work

Get To Know The API

This might seem obvious, but read the docs of whatever API you’re working with. This is really the starting point on figuring out how you can do the thing you want to do. Reading through, you might even find a better way to do something than you initially thought. A good API is intuitive and predictable, but even good APIs can have odd, unexpected behaviour in places. Look at examples too as they can really help in cases where the documentation is dated or sparse.

Keeping API documentation up to date is not always easy, so if you find some place where it’s wrong, someone will be very happy if you report it.

Use Libraries, Tools, and SDKs

A company with an API wants it to be used, so often they invest time and effort into making things that will make your life using it easier (like this!). Take advantage of the work they did for you and consider using libraries or SDKs they’ve provided. If a company doesn’t have an SDK, or if what they have doesn’t fit your language or framework of choice, take a look for a 3rd-party solution (often API docs will list a bunch of these in addition to company-build ones).

Using an SDK or library isn’t generally required, but there are advantages to not having to reinvent the wheel. Many of the topics I’m going to cover next might already be handled by a well-built SDK! Often SDK developers know the API quite well (especially if they’re employees of the company) and they can often simplify, clarify, or even paper over those oddities or inconsistencies I mentioned in documentation.

For example, for historical reasons a lot of the oldest accounting endpoints in FreshBooks’ API return dates in North American Eastern Time (US/Eastern aka EST/EDT, time zones are complicated), while all newer endpoints to return dates in UTC (we’re moving everything to UTC, but it takes time). If you’re using one of our SDKs, we hide that from you and return all the dates in UTC. We’ve done the work so YOU don’t have to figure out which is which!

Just like documentation, if you find a bug or missing feature in a tool, the owner would love your feedback, and if it’s open source and you’re keen, you could even try to fix it yourself.

Limit The Scope of Requests

For your own benefit, as well as the API owner’s you want to fetch data in an efficient way. This means not grabbing data that you don’t care about and will just throw away, as well as not fetching too much data at once and then having memory or performance issues trying to process it that can spill over into slow responsiveness for your users.

This means that you should look at how an API handles filters (to limit returned records to only those you care about), pagination (fetch records in smaller batches so you can handle them in chunks), sorting (so those batches come in an order that works for you), and maybe even what fields are included in the response (so the record itself isn’t filled with data you don’t need). Here is FreshBooks’ Search, Paging and Includes documentation.

For example, one integration I was debugging would sync invoices from another service to a particular client. It would check to see if that existed before creating it:

const matchingClients = await freshbooksClient.clients.list(accountId)
const matchingClient = matchingClients.data.clients.find(
    (currClient: Client) => currClient.organization === clientOrganization
)

But it was sometimes creating duplicate clients. This was because FreshBooks defaults to returning 30 records at a time with the newest ones first. This worked fine when it first created the client, but as customers used the app and made more clients, the client to sync with got bumped off of the first 30 results and was no longer found. In addition to that, the code was fetching as many clients as it could, and then filtered them in memory. It either needed a filter or pagination (or both).

const clientSearchQueryBuilder = new SearchQueryBuilder().like('Organization_like', clientOrganization)

const matchingClients = await freshBooksApi.clients.list(
    currentUser.fbAccountId,
    [searchQueryBuilder]
);
if (matchingClients.data.clients.length > 0) {
    const matchingClient = matchingClients[0]
}

Let the API do that work!

Properly Handle Errors

There’s a lot to proper error handling, so let's look at things in pieces.

API Errors

A lot of API docs will have information on error codes, states, messages. You don’t want your integration to break unexpectedly, so you should look to handle these. Logging response messages is really helpful when building an application to understand business rules or validation failures. When you’re up and running in production, it’s equally important to help you know why something might be failing. For example, a good API won’t just give you a 422 Unprocessable Entity, but might return a message like 422 - At least one field among first_name, last_name, email or organization is required (a FreshBooks client validation error message)

The API isn’t your code, and you don’t control what comes out. This is a black box, and it’s helpful to follow defensive coding practices. You should check http response codes, wrap your calls in try/catches, etc.. Don’t assume that a response you get has an object or resource data structure as a failure may return an error data structure instead, so you should be prepared to parse or otherwise handle either. If a REST APIs backend service is down, a company’s API gateway might not even return you JSON but instead give you an HTML error page that your JSON-expecting code will just fail to parse. In short, don’t assume that the response will always come in the form you expect, and ensure you handle cases when it doesn’t.

Timeouts and Connection Exceptions

The API you're using isn’t perfect. It could be slow or offline. In these cases, your integration could run into issues if all the processors or workers are stuck waiting on the API. For this reason, you should configure timeouts on your calls. HTTP clients have easily set timeouts but often they are not enabled by default. Again, a good SDK will have some sane defaults for you (we default to 30 seconds but let you easily override).

In general there are connect timeouts (how long you wait to establish a connection), and read timeouts (how long you wait for the response). Some clients let you set them together or individually, but you’ll want to set both to protect from an unresponsive server (connect), or a really slow response (read).

Figuring out exactly what the timeout values should be is very dependent on your integration and the API you’re using, but even setting them to something high (15-30 seconds) can save you a lot of pain.

Rate Limits

Most APIs will limit traffic to prevent a bad actor from hindering other integration’s performance or degrading the entire system. You should build your integration to respect and accommodate these limits. Running up against them constantly doesn’t do you any good, as your work won’t get done faster, and could result in your integration being banned.

As mentioned above, it’s best to build your integration with efficient calls in mind. Reducing the number of calls you need to make means you’re less likely to hit call limits.

Another good practice is to properly handle rate limit errors (generally HTTP 429 errors), and then rather than retry right away, wait for a bit before making the next call. If the next call is still limited, wait even longer. This is called an exponential backoff, and again, most HTTP libraries will have a way to enable this and many SDKs will have implemented this (our SDKs do it here and here).

Do More Asynchronous Work

If your integration is handling a lot of data via an API, you should consider moving as much work to asynchronous tasks as possible. In this way you can not block your users, manage and throttle your work loads, and easily retry failures. The above advice on handling rate limits gets a lot easier if your processing code isn’t blocking user actions while retrying. It also lets you throttle the calls in whatever queue system you’re using.

Look into Amazon’s SQS, Google’s Cloud Tasks queues, Python’s celery and something like CloudAMQP, or Bull with Redis. There are a lot of options out there.

Another good idea is to use webhooks if the API supports them (FreshBooks does). This allows you to register to receive messages when an event happens. Rather than polling an API every 5 minutes to see if a new resource has been created, you can tell the API to send you a message when that happens. This can save you a lot of calls and overhead.

Going back to that old integration I was debugging, it would sync invoices with FreshBooks every 20 minutes, but the process involved gathering up all the invoices it hadn’t pushed and looping through them. However, the process was driven by a synchronous HTTP call that would timeout after just a couple minutes, killing the process. It could take days to move everything over. Calling the process more often would only help a little as there were only so many calls the service could handle at one time and these long-running calls could block workers from handling user interaction with the app. We redesigned the whole sync process of the integration so that everything was done in small asynchronous tasks. On first signup we had an async task that would fetch each invoice (paginated), and put a message on the queue to process that invoice. The invoice processing tasks could thus be retried, scaled up, or throttled as needed. We also utilized webhooks for real-time updates. Each event received would just create another invoice process task. Instead of days, things could be processed in seconds, minutes, or perhaps hours for very large workloads.

Go Out And Build

Well, I hope that gives you a few ideas on building a robust integration. If you know the API you’re using and the tools available, keep your calls efficient, handle the unexpected gracefully, and keep your time consuming processing away from the user’s actions, you’re on a great path to succeed. If you have any questions, please reach out to me, and if you have anything related to FreshBooks’ API you can email newapi@freshbooks.com.