DEV Community: Anvil

Understanding The Styled System

Anvil Engineering — Thu, 08 Jul 2021 22:43:44 +0000

The landscape of CSS has dramatically changed over the years and nowadays you'll find many developers emphatically love CSS-in-JS. First-time CSS-in-JS users often recognize one huge benefit: "Hey, I don't have to toggle between CSS and JS files anymore? Sweet!" While that is an incredible time saver, today I'll be writing about the Styled System, a popular framework for getting the most out of CSS-in-JS and saving you significantly more time.

The Power of CSS-in-JS

If you are already familiar with CSS-in-JS, you can skip this section. I will be recapping its capabilities and highlighting the most important features.
At Anvil, we use styled components in our React applications. From this point on, I will use 'CSS-in-JS' and 'styled components' interchangeably and all examples will be with the styled-components library.

By bringing CSS to JS we not only save files written, but add all the dynamic capabilities of JavaScript to our styles. During your build step, your styled components will be compiled down into an optimized JavaScript bundle (or bundles, if you have multiple configured) and regular CSS classes directly in the head of your HTML. No CSS stylesheets whatsoever, just optimized CSS ready to go in a style tag where needed.

Here is an example of how to write a centered, blue box with styled-components:

import styled from 'styled-components'

// definition
const BlueBlox = styled.div`
    width: 300px;
    height: 300px;
    margin: 0 auto;
    background: blue;
`

// usage
<BlueBox>I am some text within the blue box!</BlueBox>

This example is literally CSS embedded into JavaScript. Pretty neat, but what if we want multiple boxes of different colors? In regular CSS land, we would have to create a different class for each color… kinda lame to repeat yourself right? Let's use JavaScript and dynamic props to optimize our styled component.

Since the color is going to change, our BlueBox component doesn't make sense. Let's rename it to ColoredBox:

import styled from 'styled-components'

// definition
const ColoredBox = styled.div`
    width: 300px;
    height: 300px;
    margin: 0 auto;
    background: ${(props) => props.backgroundColor};
`

// usage
<ColoredBox backgroundColor=”blue”>I am the original blue box!</ColoredBox>
<ColoredBox backgroundColor=”red”>I am a new box, my background is red</ColoredBox>
<ColoredBox backgroundColor=”yellow”>Primary colors ftw! Yellow is here as well.</ColoredBox>

This is much better than our old BlueBox component. By passing a property of backgroundColor, we are able to easily write different styles of boxes, never worrying about writing new CSS. This power extends to any imaginable CSS out there; you can pass hex values, rgba values, hsl values, etc. to our backgroundColor prop and it will work. I won't go into detail here in this recap, but you can pass entire style objects with multiple CSS properties dynamically as well. Check out one of my personal favorites from styled-components, the css mixin.

Now that we have the syntax of CSS-in-JS fresh in our minds, let's dig into why we're here: the Styled System.

The Styled System

As the name suggests, the Styled System employs a systematic approach to building components. The systematic approach comes in the form of enabling common style use cases directly in JavaScript. In the above example we saw how to dynamically set the background color using styled-components; imagine a world where you didn't have to write any CSS at all and could still achieve the same result.

That is precisely what the Styled System does: it provides style props that you use when writing JavaScript that take care of all the CSS mess for you. Let's see how to implement our ColoredBox component using the style props from the Styled System.

import styled from 'styled-components'
import { color, layout, space } from 'styled-system'

// definition
const ColoredBox = styled('div')(
  color,
  layout,
  space,
)


// usage
<ColoredBox bg="yellow" width={300} height={300} m="0 auto">Styled System rocks!</ColoredBox>

Here are the two yellow boxes, for reference:

ColoredBox without the Styled System:
ColoredBox with the Styled System:

Same result, but with our style props we get an almost one-line solution. Let's recap what we did:

imported the appropriate objects from styled-system (color, layout, and space)
defined a styled component (ColoredBox) using the style props
used our component in the exact way we want to. Repeat this step for any imaginable ColoredBox, whenever and however you want!

By using the Styled System, all of the specifics are pushed to the time we actually need to specify them, e.g. when actually using the component.

Abbreviated Style Props

You'll also notice I used bg for background color and m for margin in the above example. A secondary benefit of the Styled System are abbreviations like these, plus a few other helpful ones. It isn't the biggest time saver, but typing bg versus background or background-color every time is definitely easier on the fingers. My personal favorites from this convention are horizontal and vertical spacing.

Along with m for margin, you get p for padding. Similar shorthands exist for each direction, so for padding you get: pt for padding-top, pb for padding-bottom, pl for padding-left, and pr for padding-right. Horizontally, you could define pl and pr, but why waste time writing both? Use px, and the Styled System will apply your horizontal padding for you to padding-left and padding-right. Pretty sweet bonus, since there's no native way to do a one liner for just left and right spacing. This applies to all spacing properties, and there is indeed a py for vertical spacing.

Benefits of The Styled System

By using this framework and its pattern, you unlock a multitude of benefits that it supports. You can read more about the benefits of the Styled System here, but the two we will focus on throughout this blog post are:

Style props that pick up values from a global theme
Quickly set responsive font-size, margin, padding, width, and more

Theming

We have seen how the Styled System provides style props for us, allowing dynamic styling. But where should the actual style values reside? The answer is up to you and truly depends on your needs; if you are doing a side project by yourself, starting out with hardcoded values is a perfectly valid option.

Where things get complicated is when you have a team of people building a real product. What shade of red are we using for the logo? What shade of red are we using for a button to indicate a dangerous action? Two very different scenarios, but very easily confused if using hardcoded values.

Styled System solves this problem by providing a way to theme your application. It uses object notation via the System UI Theme Specification. This theme object falls under an age-old information architecture adage: Single Source of Truth. By adhering to a theme, you are enforcing consistency across all components and pages of your application, while also enabling easy swapping of values. Think of all the 'dark mode' web apps and sites out there; each has some notion of theming, in which style values are swapped based on what theme is chosen. For each of those sites, the components themselves don't change, but the style values do.

The System UI Theme Specification works primarily on the idea of scales. Spacing and typography are defined using arrays in which each element is incremented by the same amount. For open-ended values like colors, an object is used to define values. And lastly, the keys in our theme object correspond to the pluralized, camel-cased form of the underlying CSS property, e.g. color will be colors, font-size will be fontSizes, and so on. The only exception is the space key, which represents all space properties, including all margin and padding variants.

With all that being said, everything is configurable. Besides the naming convention, your scales can be implemented however you want or you don't have to include a scale at all. Depending on how you actually use the theme, you might not even need to follow the naming conventions laid out in this article and on the System UI Theme Specification itself. But be warned, you miss lots of built-in benefits if you stray away from the convention!

Here is an example of a complete theme:


const black = '#222222'
const blue = '#00C0F2'
const red = '#FF5C5C'
const yellow = '#F8BF95'

const colors = {
  blacks: {
    5: '#fafafa',
    10: '#d8d8d8',
    20: '#bbb',
    30: '#999',
    40: '#7a7a7a',
    50: '#525252',
    60: '#3d3d3d',
    90: black,
  },
  blues: {
    10: '#F4F6F9',
    20: '#def3f7',
    30: blue,
    40: '#00ABD7',
  },
  reds: {
    30: red,
  },
  yellows: {
    30: yellow,
  },
  black,
  blue,
  red,
  yellow,
}

colors.textColor = colors.black

const space = [0, 5, 10, 15, 20, 25, 30, 35, 40]

const fontSizes = [12, 14, 16, 18]

const fontWeights = {
  light: 200,
  thin: 300,
  normal: 400,
  bold: 700,
  black: 900,
}

const fontStack = 'Comic Sans, -apple-system, BlinkMacSystemFont, sans-serif'
const fontFamilies = {
  body: fontStack,
  heading: fontStack,
}

export default {
  colors,
  space,
  fontSizes,
  fontWeights,
  fontFamilies,
}

ThemeProviders

Of the many ways to use a theme object, using a ThemeProvider (if one is provided by your CSS-in-JS library) is the best way to go. It leverages the React context API to pass down your theme values to all components of your application.

Taking the example from Styled System itself:

// in App.js
import React from 'react'
import { ThemeProvider } from 'styled-components'
import theme from './theme'

const App = props => (
  <ThemeProvider theme={theme}>{/* application elements */}</ThemeProvider>
)

export default App


// in any other component, this will pick up 'black' and 'blue' from our theme!
<Box color="black" bg="blue">
  Blue Box
</Box>

Element Variants

Our last stop for theming an application is adding element variants to your theme. There currently exist 3 included element variants: buttons, textStyles, and colorStyles. While we don't use element variants at Anvil, they are pretty sweet upgrades to base styles in your theme and can seriously help your style writing productivity.

Element variants work by grouping any style you want to apply and assigning it to a key. Below is an example for buttons; if you have used CSS frameworks like Bootstrap before, these variants should feel familiar.

// theme.js
const buttons = {
  primary: {
    color: colors.white,
    backgroundColor: colors.blue,
  },
  secondary: {
    color: colors.white,
    backgroundColor: colors.green,
  },
  danger: {
    color: colors.white,
    backgroundColor: colors.red,
  },
}

export default {
    buttons,
}

// using a button variant
<Button variant='primary' />

Responsive Styling

“Quickly set responsive font-size, margin, padding, width, and more” sounds a bit odd and hard to quantify. Responsive Design revolutionized the web, but how do you set that up quicker than a few media queries and use the max-width property?

The answer is by combining the previous section (theming your application) with defined breakpoints for your entire application.

Similar to theming, defining breakpoints for your application provides consistency and better maintainability. I won't go into the nuances of responsive design and what are good breakpoints to set, but a 'breakpoint' is where your application's style changes based on the viewport width. For example, a widely accepted breakpoint is 769px for tablets; anything above that is considered wider than a tablet, so the next breakpoint's styles would apply.

Writing media queries for each page or each component of your application gets tiring, fast. The Styled System makes it a breeze by passing your breakpoints to a ThemeProvider, which now gives all components created with Styled System the ability to take arrays as values instead of their normal values. Each value in the array corresponds to the value that will be applied at each one of your specified breakpoints, which is incredibly easy to write compared to media queries.

For example:

// passed to ThemeProvider
const breakpoints = [600, 800, 1000];


// using breakpoints

<Box
  width={[
    1,    // 100% below the smallest breakpoint
    1/2,  // 50% from the next breakpoint and up
    1/4   // 25% from the next breakpoint and up
  ]}
/>

// responsive font size
<Box fontSize={[ 1, 2, 3, 4 ]} />

// responsive margin
<Box m={[ 1, 2, 3, 4 ]} />

// responsive padding
<Box p={[ 1, 2, 3, 4 ]} />

Each of these Boxs will have media queries set up to do the responsive design for you, using a mobile-first approach. For the last three Boxs, there are 4 values despite 3 breakpoints; in this case, the last value is for any viewport width over the last breakpoint of 1000px.

Reflexbox

At Anvil, we use responsive styling via the Styled System extensively. We use a component provider called Reflexbox by Rebass, which is an entire suite of prebuilt primitive components to use. Instead of reinventing the wheel, we utilize these components from Reflexbox to build our components with ease.

I recommend you read the docs for Reflexbox, but fun fact--you already know how it works! There are 2 components built with the Styled System, Box and Flex. Box takes the layout, space, color, and typography props, while Flex has all of those plus flexbox props. Both components support responsive styling as well 🤘🏼

Putting it all together

In this blog post we covered the Styled System in-depth. If you are developing using the Styled System, you likely do not need to know such a granular level of detail, but like all things in software development, you tend to grok the technology the more you dig into it.

We saw how CSS-in-JS enables much more than less source code files, but truly rapid component and style development. We also saw how theming and responsive styling streamline app development and provide consistency throughout entire applications, while enabling easy maintainability for style values.

I'll leave you with one tidbit on the limitations of the Styled System: not all CSS values are supported. If you look into the color prop source code, you'll find this:

import { system } from '@styled-system/core'

const config = {
  color: {
    property: 'color',
    scale: 'colors',
  },
  backgroundColor: {
    property: 'backgroundColor',
    scale: 'colors',
  },
  opacity: true,
}
config.bg = config.backgroundColor

export const color = system(config)
export default color

This looks well and good, but config.bg raises a question or two… We can use bg on a component to set the background-color, but how about background-image? The CSS background property is shorthand for 8 other properties (yes, 8!), yet only 1 is truly supported here. These are common things we can do in CSS, but the way this is implemented we can't do with the Styled System.

Luckily for you and me, we can define our own custom props. Quite an amazing system, if we can extend it like this!

I hope you enjoyed this blog post, and if you write your own custom props we'd love to hear about it. Send us a message at developers@useanvil.com, and we'll publish all the ones we get. Happy coding 🤘🏼

Announcing the Anvil HTML to PDF API

Anvil Engineering — Mon, 26 Apr 2021 18:33:34 +0000

Recently we launched a PDF API that included a PDF generation endpoint. The endpoint allows you to generate brand new PDFs with Markdown.

Since launch, the most heavily requested API feature has been HTML to PDF. Developers said they want full control and they want generated PDFs to exactly match their brand.

Today, I'm excited to announce that HTML to PDF support is available to all! Now, you can easily generate PDFs that look exactly the way you want, using your own colors, styles, and layout language.

An example invoice PDF:

In a hurry? Check out the HTML to PDF docs, and our invoice example repo.

anvilco / html-pdf-invoice-template

An HTML invoice template for use in a browser and with HTML to PDF generation.

How it works

The HTML to PDF endpoint uses our existing PDF generation endpoint, but in addition to an array of objects, it accepts vanilla html and css strings.

POST https://app.useanvil.com/api/v1/generate-pdf
{
  "type": "html",
  "data": {
    "html": `
      <h1 class='header-one'>What is Lorem Ipsum?</h1>
      <p>
        Lorem Ipsum is simply dummy text...
      </p>
    `,
    "css": `
      body { font-size: 14px; color: #171717; }
      .header-one { text-decoration: underline; }
    `,
  },
}

That's it! All the HTML and CSS you're used to can be sent up and rendered in PDF form.

See the HTML to PDF docs for information on all the options you can pass to the /api/v1/generate-pdf endpoint.

Using language-specific clients

The new HTML to PDF features are also supported by our client libraries:

anvilco / node-anvil

Node API Client for Anvil

anvilco / python-anvil

Python library and CLI for the Anvil API

First you'll need an API key. Sign up for Anvil, then get your API key.

Here's an example in node, replace YOUR_API_KEY with your key, and HTML/CSS with your own code:

const fs = require('fs')
const path = require('path')
const Anvil = require('@anvilco/anvil')

const client = new Anvil({ apiKey: YOUR_API_KEY })
const example = {
  type: 'html',
  title: 'HTML Invoice',
  data: {
    html: '<h1>...',
    css: 'body { ... } ...',
  },
}
const { statusCode, data, errors } = await client.generatePDF(example)

if (statusCode === 200) {
  fs.writeFileSync('invoice.pdf', data, { encoding: null })
} else {
  console.log(statusCode, JSON.stringify(errors || data, null, 2))
}

And in python:

from python_anvil.api import Anvil

anvil = Anvil(api_key=YOUR_API_KEY)
data = {
    "title": "Example Invoice",
    "data": {
        "html": "<h1>...",
        "css": "body { ... } ..."
    }
}

response = anvil.generate_pdf(data)

Beyond the browser

Since your HTML & CSS will be rendered for a PDF instead of a browser, there may be special considerations you want to make given the medium. For example, page numbers don't make sense in a browser, but they do in a PDF.

There are a few extra PDF-specific CSS features available that allow more control for PDF rendering. We'll go into more specifics in subsequent posts. For now, here are a couple of interesting features covered in our invoice example.

Rendering in the margins

Many PDFs have page numbering rendered on each page's margins. With the API, you can control what is rendered in the margin at each corner. In our invoice example, two items rendered are in the bottom margin:

Bottom left: an arbitrary element is rendered on the last page only
Bottom right: numbering has been added to each page and styled

Repeating table headers

In a browser, a table cannot overflow to another page, but in a PDF, it can! When a table overflows, by default the API will repeat the table's headers on the next page:

An example

We've put together an example HTML/CSS invoice template, demonstrating the features mentioned above. It contains HTML and CSS that renders both in the browser and the API. Included is an example node script to help you quickly generate PDFs.

Check it out to jumpstart your integration!

Onward

At Anvil, we're on a mission to abstract away PDFs for developers. Hopefully this new HTML to PDF feature is a big step in making working with PDFs effortless.

Lastly, if you’re developing something cool with PDFs and/or paperwork automation, we’d love to hear more from you! Let us know at developers@useanvil.com.

Introducing the Anvil API Python Library

Anvil Engineering — Mon, 26 Apr 2021 04:46:06 +0000

The Anvil API is now supported on Python via our official client library. The library is available now on GitHub:

anvilco / python-anvil

Python library and CLI for the Anvil API

and as a package through PyPI via pip install python-anvil or your preferred package manager (i.e. pipenv, poetry).

As a company, we are heavily invested in the Javascript ecosystem; however, we also realize that making our platform more developer-friendly and accessible to other developers means increasing our official API library footprint. That’s why we’ve added Python to our client library as another step towards building a more developer-friendly Anvil. We hope this release gives developers an opportunity to enjoy all that Anvil has to offer.

Features of this initial release:

Keeping in line with current Javascript library, it includes:
- Filling PDFs
- Generating PDFs
- Creating Etch Signing Packets
A command-line interface (CLI)
- Contains the above, giving you the ability to test out our features in the Python REPL.
- The anvil command from this package also has a few additional useful commands that will help you as you build out your integration, such as getting a list of PDF templates (or casts) for use in the “fill-pdf” API endpoint, as well as getting field data from a specific PDF template. All of this can be done from the comfort of your text-based terminal.

Filling PDFs

Filling PDFs lets you fill PDF templates created on Anvil with a simple API call.

First, create a template on your Anvil dashboard:

Once uploaded, Anvil will attempt to find fields for you. You can also create your own fields and adjust any field types if you need something specific such as date formats.

When you finish editing fields, click over to the API Info tab. It shows everything you need to fill the template with the API, including an example payload to quickly get started.

With the data on the API Info page, you can now create your API call. The resulting response will be the PDF file:

from python_anvil.api import Anvil

anvil = Anvil(api_key="MY API KEY")
data = {
    "title": "IRS W-4",
    "font_size": 10,
    "data": {
        "someFieldName": "Example data",
        "aNumberField": 1234
    }
}
response = anvil.fill_pdf("template_id_here", data)

Generating PDFs

The Anvil API also allows you to generate new PDFs using provided JSON data. Useful for agreements, invoices, disclosures, or any other text-heavy documents.

from python_anvil.api import Anvil

anvil = Anvil(api_key="MY API KEY")
data = {
    "title": "Example Invoice",
    "font_size": 12,
    "data": [{
        "content": "Supports **markdown**",
    }, {
        "table": {
            "rows": [
                ["Description", "Quantity", "Price"],
                ["4x Large Widgets", "4", "$40.00"],
                ["10x Medium Sized Widgets in dark blue", "10", "$100.00"],
                ["6x Small Widgets in white", "6", "$60.00"],
            ]
        }
    }]
}

response = anvil.generate_pdf("template_id_here", data)

Creating Etch Signing Packets

The Anvil Etch E-sign API allows you to collect e-signatures from within your app. Send a signature packet including multiple PDFs, images, and other uploads to one or more signers. Templatize your common PDFs. Then, fill them with your user's information before sending out the signature packet.

This is one of the more complex methods in the API, so please take a look at the Python Anvil docs for a closer look on the process.

Command-line interface

The included CLI gives you quick access to the methods above, as well as some additional GraphQL queries that can help with getting certain data without having to open up your browser.

When running the anvil command by itself, you'll be shown a display of support commands. Each individual command also has additional help documentation on how to use the command.

# The CLI commands will use the environment variable "ANVIL_API_KEY" for all
# Anvil API requests.
$ ANVIL_API_KEY=MY_GENERATED_KEY anvil
Usage: anvil [OPTIONS] COMMAND [ARGS]...

Options:
  --debug / --no-debug
  --help                Show this message and exit.

Commands:
  cast                Fetch Cast data given a Cast eid.
  create-etch         Create an etch packet with a JSON file.
  current-user        Show details about your API user
  download-documents  Download etch documents
  fill-pdf            Fill PDF template with data
  generate-etch-url   Generate an etch url for a signer
  generate-pdf        Generate a PDF
  weld                Fetch weld info or list of welds

Lastly, if you’re developing something cool with PDFs and/or paperwork automation, we’d love to hear more from you! Let us know at (email here) if you have any feedback. Also, if there are any suggestions on new features or issues you may encounter for this library, let us know on the Issue section of the GitHub repo page, and we’ll get back to you.

Tackling the mighty PDF with Anvil

Anvil Engineering — Mon, 26 Apr 2021 04:44:10 +0000

Full Transcript of video below - lightly edited for clarity

Hello everyone. My name is Ben. Today's talk is about tackling the mighty PDF. So we'll start with a little bit of context about PDF and then we'll get into some code stuff. We’ll talk about the challenges of working with PDFs, some of the challenges that we faced and then I'll demo some things that hopefully make working with PDFs a lot easier.

So co-founder CTO of Anvil, little bit of background, I have been a developer for a long time. Previous to Anvil, I worked at GitHub on the Atom editor and before that I founded a design tool startup.

The PDF kind of needs no introduction, but I want to give like a little bit of context before we dive into the code things. So you've done this before, you've got an email from somebody with a PDF that's asking for all of your most personal information. So you fill it all out and you mail it back, and you aren’t sure exactly where your data is going to end up. I know, not a lot of people like doing this, I sure don't but it's super common.

Most email attachments are PDFs, like most non cat picture email attachments are PDFs, and they're everywhere! If you had to guess how many PDFs were out there, what would you guess? Would you say like a billion? Ha ha. Would that be exaggerating? Turns out that there's two and a half trillion PDFs. That's not necessarily unique PDFs, but it's a lot of PDFs.

There's 20 billion PDFs just in Dropbox.

So there are some really good uses of PDFs aside from forms.

Resumes, ebooks, we submitted these talk slides by PDF, academic papers and one of my favorite uses that I just learned about is fashion specs. So all of these have a couple things in common, what do they have in common? They are all for consumption and sharing,
PDFs are really good for things that you don't need to edit, you're not editing the PDF. You're not filling something out in the PDF.

All you're doing is you're reading them. So I think we can say that PDFs are really good for screens and for printers and this makes a lot of sense, because this is what PDFs were originally built for, they were built to display information exactly the same across all devices. Also be shareable.

So that way you can send your underwear PDF to the underwear factory and get them made exactly like you want them to, be because they don't worry about them having fonts or not. It'll look exactly the same as the way that you intended.

But the most common way that people have interacted with PDFs, certainly for me, is by filling out PDF forms. PDF forms are really annoying for a couple of reasons. Yes, one is that there's a lot of repetition so you have to fill out your name six times or fill out several PDFs with the exact same information. There's also a lot of PDFs that have logic, so you have to read and understand part of the PDF, and then make decisions.

So this is a 401k tax form. If you want to take money out of your 401k, there are complications, because it depends on your situation. So this is obviously complicated right? It turns out that humans are really bad at this.

They're really bad at filling out PDFs. A professional data entry person's error rate is 4% but I know that my error rate is a lot higher, unless I'm really really paying attention, and we've heard from our customers that their customers make a lot of mistakes.

Yes, so it is really good for screens and for printers, but maybe not so great for humans because filling out these forms is interesting.

Okay. So what would be better than having humans do it? Computers are obviously a lot better than having a human fill it out. Computers are really good at logic and repetition. So it makes sense that they could think and sort of make these decisions we can ask the user. What's your name, and your birth date, and your address, and then we can basically with a couple of pieces of information fill out all of those check boxes and fill out all the right fields. This is what we want.

We don't want people to be interacting with these forms. How do we abstract away of the PDF? We can't get rid of the PDF because there's two and a half trillion of them. And behavior change is really hard. But I think that we can make it so that no human has to deal with PDFs.

All right, so I guess the question is how do we interact with PDFs as developers? Do we go and read the spec? Probably not. I don't think anyones gonna do that. I certainly haven't read all of the PDF spec or the HTML spec and I write a fair amount of HTML. It's huge. It's complicated. What do we do? We are going to find a library on the internet. When we were starting Anvil, this is exactly what we did, we went to the internet and we were like, “PDF filling libraries”. What we learned is that developer attention to the technology is important. Some technologies have a lot of attention from developers, take web technologies.

It was created sort for the same reasons as PDF for display and consumption and that kind of thing, for sharing academic papers. But since then it's had like insane developer adoption. There's literally millions of developers building things. Like for the web, on the web, they’re building web libraries, there's people complaining on issues, there's people fixing those bugs. And what all of this collaboration results in is a bunch of really well made, maintained, high level libraries. They have good doc's, you know, they're updated all the time. So in this world, you're never interacting with the DOM APIs, you're actually interacting with react, sass and typescript and all of these cool technologies that people have built on top of web tech. So as a developer, I’ve become super accustomed to this kind of thing. I’ve got a problem. I can go to GitHub, I can find a library that does mostly what I want.

But PDF Tech isn't really there yet compared to web development. there's very few developers looking at it, so like every human has to deal with PDFs, but there aren't so many developers looking at this.

All right, there are libraries though and they generally fall into two categories. They're complete or incomplete. So the complete libraries can do everything that you would maybe want to do with a PDF. You can read them, you can write them, you can update them. On the incomplete side, they usually just do like one tiny thing, and often these incomplete libraries aren't well-maintained, haven’t been touched in five years, you can also run headless Chrome to generate PDFs, but you can't update a PDF with Chrome

So the complete side seems really good. Right? This is the route that we went down. But like the DOM APIs they're pretty low level. So you have to know a lot about the PDF and how its put together to read, edit, create them. So if you're saying you want to do something simple, something seemingly simple like creating an invoice. That can lead to like a lot of overhead to set a whole thing up to create this invoice.

Okay. So now I'm kind of into the code part of things, if we are working with low-level apis. If we are working with low level APIs and we have to know about these PDF details. What are some of the challenges? So I think you see some of the challenges that we face when we are building out our PDF service. And so these are some of the challenges. So number one is layout, if you want to create a new PDF or you want to add something to a PDF you have to deal with layout. Everything in a PDF is absolutely positioned, fixed sizing and there's no text wrapping. So there's not a lot of niceties for a content creator. This logic that would wrap things and whatever, is like pushed up to these from the application layer. So coming from HTML this might be a little weird. HTML is declarative. So it's like “here's what we want to display” and the browser will make decisions based on well, how wide is this screen? Like let me shrink it down and wrap stuff. You can also give the browser guidelines with CSS by saying “OK, I want to use flexbox and I want this column to be this wide”, but the browser might ignore you, the browser is making these decisions on how to display things.

So the PDF is opposite that where you are specifying exactly how to draw a document. There's a bunch of little drawing commands in here saying okay. I want to start text. I want to pick this font. I want to move the cursor here and then I'm going to paint the text, you know from that cursor position. So HTML will automatically wrap stuff, but if we want to do that, we have to split up the lines manually. So here's an example where we did that we measure the Box bounding box. And then you measure each character and then you figure out how many words will fit into that and you break it in the lines and then use the paint all the lines yourself. So this is a challenge for us. There are some libraries you can put on top of the libraries, but it was a challenge.

The second thing I want to talk about is fonts. It seems like it should be really simple but with PDFs they're not, and I think one of the reasons is because PDFs are supposed to be self-contained and they weren't really built to be edited. So there's no fallback fonts, the font glyphs like the specific characters to render that in that font is embedded inside of the PDF. You can't mix fonts in the text block. You can't say like here's a sentence bold. This word. You have to draw those things independently. So it is HTML going back to that. This is a lot simpler. Right? Like you just specify a whole bunch of fonts and the browser will figure it out. And if we use a character that our font doesn't support the browser will find a font. That does have that character, and display it. So it's Magic!

Fonts in a PDF are a little bit more complicated. So there's a lot going on in this slide. First of all I picked this on Google called Noto and it doesn't have the “shi” character. So I can't use it. It won't render in the PDF. The second thing is that I'm drawing the regular and the Bold word independently, and on the right there, we're embedding all of the glyphs for those specific words. So from the regular we're getting the hclo and then from the bold, we're getting over the world characters. So if we were to say use a lowercase H, then it wouldn't display because it's PDF doesn't have that font. And so if you're generating a new PDF, you have to be really careful about what characters come in because it has to be in the font. So that was a challenge. The next thing is rotations. Look at this you like that seems fun right seems fine. But then you go to print it and it's rotated.Okay cool. So this happens a lot with scanned documents. They'll scan them upside down and then something in this camera software will set a rotation on the pages to be 180. So it looks to the user like it's it's not rotated but under the hood it is.

And so this is hard because if you want to read the coordinates of something or you want to add something back into the PDF, you need to sort of back out all of these rotations and figure out like what exactly is happening so that you can orient your thing that way, so it looks right to user. So like you have to know if there's partitions of the page there's this thing called a Content stream. It can be rotated, there could be rotations on form fields. So this is a challenge to serve work out like okay, we're going to add this thing into a Content stream. How's the page? How’s the content stream and we have to sort of orient our coordinate system to manage that. Okay, so that's just a couple of the challenges that we ran into. There's a whole bunch of other things that are hard as well, like dealing with forms can be complicated depending on how you want to interact with them. Signatures are like their own talk. They're crazytown! And then extracting content can also be hard because of the absolute positioning. So the last line on a page could actually be first in the file. So extracting content can be difficult. There’s a whole bunch of other things too that can be hard.

Alright. So we've established that previous are good for screens and printers, not so great for humans because it's cumbersome and error prone to fill out PDFs, fill out forms. It's also pretty hard for developers to set up and maintain something, even for simple use cases. So like, could we fix this? If a computer fills out a PDF then the filled PDF is just a consumable, it's no different than say an e-book or resume or something like that, just a piece of information that you can reference later. So then it becomes good for humans. So the last piece of this then is trying to make it so that Developers can fill out all these PDFs so that humans don't have to deal with it. And that's what we've been working on. We've been working on, and we released recently, this PDF API, that does e-signatures, PDF filling, and PDF generation with Markdown right now.

So our goal is to make these things super easy to use.

Okay, now I'll get into the demo.

Okay. I hope everyone can see that. So I'm going to take you through the three different things that we do so we have a generated PDF, what we're going to do is going to generate a brand new PDF. Generate this invoice. And so we are able to send a JSON payload to a single endpoint and it will respond with the PDF bytes. So We're going to be using our node client, which is just for authentication helpers and then also some helpers for actually calling the endpoints. I'm going to build up our data here. And then all we're going to do is create the client and send, and then generate the PDF with our data. So each one of these is like each of these objects is a section on the PDF, and they’re separated by a little bit of padding here. They support markdown and then I have some helpers for creating tables, because it's a common use case. So this thing's already generated. So I'll show you a little bit. We'll add some more stuff here. We'll add will bold. If some we will have blood this thing. Let's make this left aligned, alright sweet. So, then we generate it and then magically works and so we just automatically get markdown support. Here and table support and all that. So that's it for generating APIs.

Okay, so moving on to the filling APIs. It's similar to the generate API except that we have a template. So we have an existing template that we have already created, uploaded into our system, and the boxes were found when we uploaded it. And so each one of these boxes has an ID on it, so we are able to send data to each one of these IDs and it will fill out the template. So we are going to generate this W4. Okay, so this thing works really similar to the... first I’ll generate it, how about that.

So we got it. We filled it out. Awesome. It works really similar to the generation endpoint where we just have a payload of data and then we create the client and we send the payload with the template ID to the system. And in response with the PDF bytes, we save it to disk and that's it. So it's pretty simple to add new things. So we'll go over here and we'll add a box here, and we’ll call this “things”. Now that we've done that we have a new “things”, it supports this new box, so we can go in here and this anywhere, we generated it. Okay, so then it worked.

Cool. So that's the The Filling piece.

And so the last thing that I want to talk about is the signature packet. So this is a little bit more complicated than the last two because there's just a lot more going on. So this example what we're going to do is we're going to create a packet for onboarding a new employee. So an employee needs to fill out this W4 and then we're going to have an NDA generated for them. And then we're going to have them sign, employees going to sign both documents in the employer is going to sign one document. So two PDFs, two signers. First thing we do is we set up the email addresses. Now for this purpose of this example, and simplicity, Anvil is going to handle the signing process, it will send out emails to all the signers when it's their turn to side, but that's totally configurable. So you can set up a packet where everything is handled in your application, where it's embedded in your application. We don’t send you our users any emails. Okay. So we're going to use the email setup, so we set up the emails so that the names this works semi-similar to the other ones, in that it's just one endpoint. This is a GraphQL endpoint. We're going to call color mutation with a bunch of variables to set up a packet, and it's going to respond with some packet information. So in the variables, we set up the files, we want to use our PDF or W4. We want to upload a new NDA, and we're going to draw the boxes, and then we specify the data that we want to go onto each one of these.

These files so that's the w4 one. Here's the NDA. And then we set up the signers as well. So it's just his like which files who signs which files. Okay cool. So we are going to go to this other terminal first and then we create the Etch packet.

Alright, so we get this little URL here that it's the details URL. So this is a URL for the details of our new packet. So you can go on your dashboard. You can see the status of the packet, and see who's signed and who hasn't and all those things. Also I should have an email to sign these documents. So Sally is the employee, we are going through, and I'm going to sign.

Accept my signature, start signing, so you can see that all of this data has been filled. So the W4 has been filled with the data that we specified, and the NDA has been filled with the data that we specified. So all we need to do is then sign this.

And it's waiting then for the employer. So get a new email. So this is the employer side of things. And then we can see all of the signatures, we can see Sally's signature here, and then we can see Sally’s signature there. We sign it and it's all done, so with that, everyone gets a “completed” email. and also we can see it on the dashboard. Okay, great. That’s all.

Resources

To sign up for our free developer sandbox or learn more about our API, head over to our developer center at www.useanvil.com/developers. There, you will find comprehensive documentation, simple tutorials, and client libraries to help you get started quickly and easily.

If you have questions, please do not hesitate to contact us at:
developers@useanvil.com

New PDF Generation Features: customizable font size, color, table gridlines, and alignment

Anvil Engineering — Mon, 26 Apr 2021 04:40:03 +0000

For this blog post, we’ll assume you’re already familiar with Anvil’s API. In case you’re not, I recommend taking 5 minutes to read this tutorial on generating an invoice PDF to quickly get up to speed.

There’s tools to simplify almost all daily tasks, but when it comes to PDFs, it’s quite lacking. Anvil is on its way to changing that, and today I’m excited to announce a number of new features to further streamline PDF generation.

Overview

With Anvil’s PDF generation API, the input is accepted in JSON format with the content as an array of objects defined under the data key.

{
  "title": "Anvil Doghouse Project Invoice",
  "fontSize": 18,
  "textColor": "#171717",
  "data": [
    {...},
  ]
}

Let’s first take a look at the new features.

Per field customizable font size and color
Option to show or hide table row and column gridlines
Adjustable table column widths
Vertical alignment of table content

We’ll go through with a brief description of each feature then demonstrate them with an example.

Feature 1. Adjusting font size and color on each field

Each object under the data array is a field, and with the new release you’re able to adjust the font size and color of each field. Define fontSize and textColor to your liking on each field object, and you’re good to go.

If not specified, the font size and color will be inherited from the PDF body.

"data": [
  {
    "content": "March 4th, 2024",
    "fontSize": 16,
    "textColor": "#616161"
  },
  {
    "label": "To",
    "content": "Phoebe Beckett - phoebe@example.com",
    "fontSize": 12,
    "textColor": "#006ec2"
  }
]

Feature 2. Displaying table row and column gridlines

In the case you want your table content to be more structured and defined, the rowGridlines and columnGridlines booleans are your friend. To add gridlines in-between each table row, set rowGridlines to true. Likewise for columnGridlines.

"data": [
  "label": "Building material expenses",
  "table": {
    "rows": [
      ["Description", "Quantity", "Price"],
      ["3x Roof Shingles", "15", "$60.00"],
      ["5x Hardwood Plywood", "10", "$300.00"],
      ["80x Wood Screws", "80", "$45.00"]
    ],
   "rowGridlines": true,
   "columnGridlines": true,
   ...
  },
  ...
]

Feature 3. Adjusting table column width down to the pixel

This is another feature for tables, giving you more control of how your tables are formatted. Under columnOptions, specify your width in either pixels or percentage.

For the example below, column 1 is defined to have a width 60% of the table’s total width and column 3 would have a width of 200px.

"data": [
  "table": {
    "rows": [...],
    "columnOptions": [
      { "align": "left", "width": "40%" },
      { "align": "left" },
      { "align": "left", "width": "200px" }
    ],
    ...
  },
  ...
]

Feature 4. Vertically aligning table content

Horizontally aligning content is already supported within our tables, and now you can add vertical alignment! Set verticalAlign to top, center, or bottom to adjust the vertical position of your table content.

"data": [
  "table": {
    "rows": [...],
    "columnOptions": [...],
    "verticalAlign": "center",
    ...
  },
  ...
]

Summing It Up

What better way to summarize all our new features than with an example? Here is our PDF generation API endpoint, improved with more customizability.

{
  "title": "Anvil Doghouse Project Invoice",
  "fontSize": 18,
  "textColor": "#171717",
  "data": [
    {
      "content": "March 4th, 2024",
      "fontSize": 16,
      "textColor": "#616161"
    },
    {
      "label": "To",
      "content": "Phoebe Beckett - phoebe@example.com",
      "fontSize": 12
    },
    {
      "label": "From",
      "content": "Anvil Inc. - hello@useanvil.com",
      "fontSize": 12
    },
    {
      "label": "Building material expenses",
      "table": {
        "rows": [
          ["Description", "Quantity", "Price"],
          ["3x Roof Shingles", "15", "$60.00"],
          ["5x Hardwood Plywood", "10", "$300.00"],
          ["80x Wood Screws", "80", "$45.00"],
          [...]
        ],
        "columnOptions": [
          { "align": "left", "width": "60%" },
          { "align": "center", "width": "100px" },
          { "align": "right" }
        ],
        "verticalAlign": "top",
        "firstRowHeaders": true,
        "rowGridlines": true,
        "columnGridlines": true
      },
      "fontSize": 10
    },
    {
      "label": "Food expenses",
      "table": {
        "rows": [
          ["Description", "Quantity", "Price"],
          ["20x Dog Biscuits", "20", "$50.00"],
          [...]
        ],
        "columnOptions": [
          { "align": "left", "width": "40%" },
          { "align": "left" },
          { "align": "left", "width": "200px" }
        ],
        "verticalAlign": "center",
        "firstRowHeaders": true,
        "rowGridlines": false,
        "columnGridlines": true
      },
      "fontSize": 10
    },
    {
      "label": "Total Amount",
      "table": {
        "rows": [
          ["**Tax**", "$64.80"],
          ["***Total***", "$784.80"]
        ],
        "firstRowHeaders": false
      },
      "fontSize": 14,
      "textColor": "#db0000"
    }
  ]
}

Now you’re all prepped up to build your own PDF programmatically from JSON input. PDFs can be tricky to deal with in all sorts of situations, but with Anvil we’ll take care of that so you can focus on solving problems more important to you.

Additional Resources

Take a look at our PDF generation API docs
Experiment with our API using the Anvil API Postman collection

Questions or feedback? Contact us at developers@useanvil.com.

PDF API vs Workflow API

Anvil Engineering — Mon, 26 Apr 2021 04:39:13 +0000

What's the difference?

Anvil PDF API

The Anvil PDF API consists of three endpoints that simplify integrating PDFs into your application. These three endpoints are:

PDF generation - Generate brand new PDFs such as invoices.
PDF filling - Fill in any existing PDF template such as IRS form W-4.
Etch e-Sign - Request signatures on PDFs from multiple parties.

With a single API request, you can prepare a signature packet by uploading a custom PDF and/or filling in an existing PDF template, and then request signatures from all signing parties.

It is called the PDF API because these endpoints operate directly at the PDF level.

For both the filling and generation API endpoints, there is no visible Anvil UI that is displayed in your application. Your application simply makes a web request to Anvil and Anvil responds with PDF byte code.

For the E-signature API endpoint, Anvil provides a signing UI that can be embedded in your application, presented in a modal, or redirected to a standalone page from your application.

Anvil Workflows

Anvil Workflows combines PDF filling, generating, and e-sign capabilities with an intuitive, web-based UI to collect information. The workflow builder allows anyone to quickly create an online experience that replaces offline paperwork processes or the need to manually develop online forms. The Workflow API allows you to programmatically interface with these workflows with seamless integration into your application. There are two flavors of Workflow APIs:

Workflow GraphQL - This is a powerful suite of endpoints for interacting with Anvil. Almost all Anvil interactions are available in the GraphQL endpoints. Start new submissions, track submission progress, lock and unlock submissions, void signature packets etc.
Workflow URL - This is a simple interface for creating new submissions to a workflow and pre-populating the workflow with data.

Depending on the level of integration and the complexity of your application, you can choose between the flexibility of the GraphQL endpoints and the ease of the Workflow URL endpoints.

Webhooks

Webhooks round out the Anvil developer platform. Webhooks can be registered for Anvil Workflows as well as the Etch e-Sign endpoint. The PDF filling and PDF generation endpoints are synchronous API endpoints, so webhooks do not apply for these endpoints.

Anvil webhooks allow you to be notified of certain events within the Anvil system. These include new submissions created, submissions complete, signings completed, and more. To get a full list of webhook events, take a look at the Anvil webhook documentation.

Which solution is right for me?

In selecting the best way to integrate Anvil via API, there are a couple of things to consider:

Application complexity
UI and UX ownership
Allocation of development resources
Pricing

Application complexity

Is the workflow you are automating a core value proposition of your product? What is the “secret sauce” of what you are trying to build, and where would you like that “secret sauce” to live?

Using Anvil Workflows can greatly accelerate your product development. If the business logic is simple or there is minimal proprietary code in your application, then using Anvil workflows can offload a lot of effort from your developers, allowing them to refocus their energy on building and improving core features. Using Anvil will help you build faster, and get to market sooner.

Alternatively, if there are proprietary algorithms, industry-specific integrations, or changing business requirements with various SLAs, then owning the workflow development cycle might be important to you. In this case, you can rely on Anvil as the PDF layer that integrates seamlessly into your existing development process.

In summary, if you require a high degree of control of the software, use the PDF API. But if you are pulling together multiple tools and the business logic is simple, Anvil Workflows are a great option.

UI and UX ownership

Is your company mainly innovating around creating a 10x better user experience? Is having a cohesive look and feel across all your customer touchpoints important?

When it comes to UI and UX, Anvil Workflows provide standardized UI components with pre-built validation. You can add custom validation but you cannot change the look and feel of each individual component. The goal is to provide a comprehensive foundation for building online forms, trading fidelity for speed. Think of the workflow platform as a higher-order software library that abstracts away the nitty-gritty of CSS styling, field validation, and component-level integrations such as Google Location API for address fields.

Alternatively, the Anvil PDF API sits in the background and operates via server-side web interactions. Other than the Etch e-sign view, there is no Anvil UI that is displayed, giving you complete control of your application’s look and feel.

Anvil Workflows can mean significantly less work for your development team at the expense of controlling the look and feel of your application. On the other hand, the Anvil PDF API is extremely simple to integrate but will require more work from your front-end developer.

Allocation of development resources

What is the best use of your time and effort? What area of expertise are your team’s skills best suited to?

When building an application, the last thing you want to worry about is wrestling with dependencies, deploying a new library, or fixing CSS styling. Hiring and recruiting teammates can be time-consuming and costly.

Anvil Workflows are easy to create, even for non-developers. You can bring on a team of operational specialists, people who understand the process, and empower them with the technical tools to build their own workflows.

The PDF API is unobtrusive, operates in the background, allowing your application to take center stage. The integration is simple but does require a deeper level of software development expertise, beyond the level of knowledge expected of non-engineers.

If you are technical, or you have a large developer team, then the PDF API is a viable option. If you are non-technical or are constrained in terms of developer resources, use the Anvil Workflow platform.

Pricing

How much do you want to spend on third-party workflow tools?

Here’s how the PDF API pricing breaks down:

PDF filling or generation: Starts at $0.10 / completion
Etch E-Sign: Starts at $1.50 / completed packet (Can have multiple signers, includes filling or generation)

And here’s pricing for the Workflow platform:

Workflow: Starts at $1 / completed submission
Workflow w/ Etch e-Sign: Starts at $2.50 / completed submission
Workflow API endpoints: Free, unlimited requests

Inquire about bulk discounts for high-volume enterprises by emailing hello@useanvil.com

Although on the surface Anvil Workflows are more expensive, they can actually be more cost effective in the long-run.
Workflows are not billed per API request, only when a submission to the workflow is completed.
The cost of developing an application from scratch can be much higher. With the Anvil platform, you can build the same application faster and with fewer developer resources.

Summary

The general rule of thumb: if you are adding PDFs as part of an existing application, or if you would like to retain posession over the business logic, UI or UX, then the PDF API is a good choice. The Anvil Workflow platform is a great option if you are looking for a fast way to deploy new workflows, want a consistent way to gather and interact with customer data, or are constrained on developer resources.

Even if you think the PDF APIs are the right choice for you today, we encourage you to explore our Workflow platform. Empowering non-developers on your team to build, deploy and manage their own workflows is an incredibly powerful paradigm shift in how businesses of the future will operate.

Whatever decision you make, Anvil’s goal is to provide a simple yet flexible platform to help you streamline paperwork and data-gathering for your business.
Resources

Anvil Developer Page - www.useanvil.com/developers
Anvil API documentation - www.useanvil.com/docs

If you have questions, please do not hesitate to contact us at developers@useanvil.com

Introducing the complete PDF API

Anvil Engineering — Mon, 26 Apr 2021 00:44:32 +0000

Anvil was started with a simple premise: paperwork and PDFs are the primary bottlenecks restricting faster adoption of digital tools in every industry. We set out to build software that bridges the past and all of its entrenched paper processes to the future of online-first, data-centric operations. Using Anvil, companies can free themselves from the burden of endless paperwork, menial tasks, and antiquated ways of working, while maintaining all that is good about long-established processes: maintaining order, ensuring data integrity, and guarding against exceptions.

On the surface, the solution appears simple. First, digitally capture some data, then fill out the relevant PDF form, and finally pass the completed form to another party. In reality, paperwork processes are littered with nuances, exceptions, and business rules, each adding to the capabilities and complexity of our product.

While Anvil’s workflow builder is a great solution for solving a large category of paper workflow challenges, some complex processes warrant a software solution built by developers with deep industry-specific knowledge. So how can Anvil play a role in helping these developers? By making it extremely easy to work with the PDFs that underpin these processes.

How did PDFs become ubiquitous?

Let’s start with an abbreviated tour of the technology that enables information sharing. Throughout history, humans have devised increasingly effective ways of sharing information farther and faster.

speech → writing → printing press → typewriter → computer

These technologies allowed for information to be created and shared faster, but the underlying medium that contained the information remained largely the same, paper.

Paper

With the emergence of computers, information could be created faster but still needed to be printed for it to be shared farther.

Enter PDFs, a coordinate-based file format created to imitate paper and describe documents so that they can easily be printed. With paper being the dominant medium for so long, it made sense for PDFs to adopt the same look and feel on a screen. But the key to the PDF’s success is the combination of:

The consistency of the PDF file regardless of the program used to view it. Just like a printed paper document maintains its form regardless of who views it, the PDF looks consistent every time it is displayed. Other file formats varied in appearance depending on the program used to open the file.
The small file size of PDFs, allowing it to be transferred easily over the internet. Remember, internet speeds were very slow in the early days, so file size mattered a lot.

With these two advantages, the PDF became a foundational transitional technology - it bridged the gap between the familiar (paper) with the new (digital).

But as the internet evolved, the consistent presentation of information diminished in importance. It is the underlying data that is important, not that the information is presented on a digital sheet of paper.

This could have been the moment to phase out PDF technology and usher in a new, modern model for information sharing. For some industries, the transition to all-digital, data-first was easy. For others, especially legacy industries hamstrung by regulatory requirements, this transition has been painful, slow, and tedious. We all agree that transacting in data over the internet is the future, but how do we get there? How do we accommodate the past while orienting ourselves towards the future?

Introducing the Anvil PDF API

Returning to our original insight:

Paperwork and PDFs are the primary bottlenecks restricting faster adoption of digital tools in every industry.

In building Anvil Workflow, we have developed a deep knowledge of PDFs: how to create them, manipulate them, and electronically sign them. We also have an extensive library of tools that make interacting with PDFs online easy. Combined, these tools can accelerate companies already building vertical-specific solutions by offloading the complexities of handling PDFs to Anvil.

Today we are announcing the complete PDF API to help companies focus on building specialized solutions for their respective industries without having to worry about the underlying paperwork. These API endpoints include:

PDF Filling - A simple solution to fill in existing PDF documents. Set up a template in minutes, then make a request to the unique template URL with data.

PDF Generation - An endpoint for creating PDFs from scratch. This endpoint supports markdown formatting and dynamic length tables.

Etch PDF E-Sign - An easy, flexible, embeddable and customizable e-signature solution that just works. You can also fill out a PDF form and/or generate a new PDF to be included in the signature packet with one API call.

These three API endpoints are designed to:

Address the broadest paperwork challenges that any technology company entering a legacy industry will encounter.
Sit in the background so that your product can be front and center with your customers, allowing you to own the critical business logic that is the secret sauce of your technology solution.
Address technical headaches of managing PDFs. Most PDF manipulation libraries are written in Java/C# etc., require self-hosting, and still need to run headless Chrome to do any PDF rendering.

Why use the Anvil PDF API?

In designing these API endpoints, we had three main goals:

Simplicity - The API can be integrated into your solution in minutes. We imagined how developers would consume our API and then designed the API to best match those use cases.
Reliability and scalability - We have tested our API under heavy, real-world load. From helping underwrite millions in PPP loans, to onboarding thousands of migrant farmworkers, Anvil is ready to scale as you scale.
Developer experience - We are developers, and we want our developer experience to be an enjoyable one. To help you get started with Anvil, we have released a number of useful tools including: a. Comprehensive and well organized documentation b. An interactive PDF e-sign tutorial c. Postman API collection d. Open source node.js client for interacting with our API e. UI tools to make templating PDFs easier and faster

Have a suggestion or idea for improving the developer experience? Let us know at developers@useanvil.com, we are always looking for insight from our community.

How it’s going

We are excited by the early use cases we have seen with Anvil. Companies across many industries have used our system to programmatically create documents for:

HR
Insurance
Financial services and banking
Legal
Education
Healthcare

These are all industries that have entrenched paperwork processes, each of which requires deep knowledge to understand. There are many talented teams building innovative vertical-specific solutions. Anvil’s complete PDF API can help them focus on the core solution instead of wrestling with PDFs. By providing the digital, web-first building blocks for PDFs, Anvil is building the technology that helps accelerate the change from data stuck on paper and PDFs to a modern interconnected world with free data exchange.

If you have questions, please do not hesitate to contact us at:
developers@useanvil.com

Implementing 429 retries and throttling for API rate-limits

Mang-Git Ng — Tue, 30 Mar 2021 17:20:10 +0000

Learn how to handle 429 Too Many Requests responses when consuming 3rd party APIs.

Most APIs in the wild implement rate-limits. They say "you can only make X number of requests in Y seconds". If you exceed the specified rate-limits, their servers will reject your requests for a period of time, basically saying, "sorry we didn't process your request, please try again in 10 seconds."

Many language-specific SDKs and clients, even from major API providers, don't come with built-in rate-limit handling. For example, Dropbox's node client does not implement throttling.

Some companies provide an external module like GitHub's plugin-throttling package for their node clients. But often it's up to you to implement.

These rate-limits can be annoying to deal with, especially if you're working with a restrictive sandbox and trying to get something up and running quickly.

Handling these in an efficient manner is more complex than it seems. This post will walk through a number of different implementations and the pros and cons of each. We'll finish with an example script you can use to run benchmarks against the API of your choice. All examples will be in vanilla JavaScript.

Quick and dirty ⏱️

Maybe you just want to get something working quickly without error. The easiest way around a rate-limit is to delay requests so they fit within the specified window.

For example if an API allowed 6 requests over 3 seconds, the API will allow a request every 500ms and not fail (3000 / 6 = 500).

for (const item of items) {
  await callTheAPI(item)
  await sleep(500) // HACK!
}

Where sleep is:

function sleep (milliseconds) {
  return new Promise((resolve) => setTimeout(resolve, milliseconds))
}

This is poor practice! It still could error if you are on the edge of the time window, and it can't handle legitimate bursts. What if you only need to make 6 requests? The code above will take 3 seconds, but the API allows doing all 6 in parallel, which will be significantly faster.

The sleep approach is fine for hobby projects, quick scripts, etc—I admit I've used it in local script situations. But you probably want to keep it out of your production code.

There are better ways!

The dream

The ideal solution hides the details of the API's limits from the developer. I don't want to think about how many requests I can make, just make all the requests efficiently and tell me the results.

My ideal in JavaScript:

const responses = await Promise.all(items.map((item) => (
  callTheAPI(item)
)))

As an API consumer, I also want all my requests to finish as fast as they can within the bounds of the rate-limits.

Assuming 10 requests at the previous example limits of 6 requests over 3 seconds, what is the theoretical limit? Let's also assume the API can make all 6 requests in parallel, and a single request takes 200ms

The first 6 requests should complete in 200ms, but need to take 3 seconds because of the API's rate-limit
The last 4 requests should start at the 3 second mark, and only take 200ms
Theoretical Total: 3200ms or 3.2 seconds

Ok, let's see how close we can get.

Handling the error response

The first thing we need to nail down is how to handle the error responses when the API limits are exceeded.

If you exceed an API provider's rate-limit, their server should respond with a 429 status code (Too Many Requests) and a Retry-After header.

429
Retry-After: 5

The Retry-After header may be either in seconds to wait or a date when the rate-limit is lifted.

The header's date format is not an ISO 8601 date, but an 'HTTP date' format:

<day-name>, <day> <month> <year> <hour>:<minute>:<second> GMT

An example:

Mon, 29 Mar 2021 04:58:00 GMT

Fortunately if you are a JavaScript / Node user, this format is parsable by passing it to the Date constructor.

Here's a function that parses both formats in JavaScript:

function getMillisToSleep (retryHeaderString) {
  let millisToSleep = Math.round(parseFloat(retryHeaderString) * 1000)
  if (isNaN(millisToSleep)) {
    millisToSleep = Math.max(0, new Date(retryHeaderString) - new Date())
  }
  return millisToSleep
}

getMillisToSleep('4') // => 4000
getMillisToSleep('Mon, 29 Mar 2021 04:58:00 GMT') // => 4000

Now we can build out a function that uses the Retry-After header to retry when we encounter a 429 HTTP status code:

async function fetchAndRetryIfNecessary (callAPIFn) {
  const response = await callAPIFn()
  if (response.status === 429) {
    const retryAfter = response.headers.get('retry-after')
    const millisToSleep = getMillisToSleep(retryAfter)
    await sleep(millisToSleep)
    return fetchAndRetryIfNecessary(callAPIFn)
  }
  return response
}

This function will continue to retry until it no longer gets a 429 status code.

// Usage
const response = await fetchAndRetryIfNecessary (async () => (
  await fetch(apiURL, requestOptions)
))
console.log(response.status) // => 200

Now we're ready to make some requests!

Setup

I'm working with a local API and running 10 and 20 requests with the same example limits from above: 6 requests over 3 seconds.

The best theoretical performance we can expect with these parameters is:

10 requests: 3.2 seconds
20 requests: 9.2 seconds

Let's see how close we can get!

Baseline: sleep between requests

Remember the "quick and dirty" request method we talked about at the beginning? We'll use its behavior and timing as a baseline to improve on.

A reminder:

const items = [...10 items...]
for (const item of items) {
  await callTheAPI(item)
  await sleep(3000 / 6)
}

So how does it perform?

With 10 requests: about 7 seconds
With 20 requests: about 14 seconds

Our theoretical time for serial requests is 5 seconds at 10 requests, and 10 seconds for 20 requests, but there is some overhead for each request, so the real times are a little higher.

Here's a 10 request pass:

⏱️ Running Benchmark Sleep between requests, no retry
Request Start: 0 attempt:0 2021-03-29T00:53:09.629Z
Request End:   0 attempt:0 200 344ms
Request Start: 1 attempt:0 2021-03-29T00:53:10.479Z
Request End:   1 attempt:0 200 252ms
Request Start: 2 attempt:0 2021-03-29T00:53:11.236Z
Request End:   2 attempt:0 200 170ms
Request Start: 3 attempt:0 2021-03-29T00:53:11.910Z
Request End:   3 attempt:0 200 174ms
Request Start: 4 attempt:0 2021-03-29T00:53:12.585Z
Request End:   4 attempt:0 200 189ms
Request Start: 5 attempt:0 2021-03-29T00:53:13.275Z
Request End:   5 attempt:0 200 226ms
Request Start: 6 attempt:0 2021-03-29T00:53:14.005Z
Request End:   6 attempt:0 200 168ms
Request Start: 7 attempt:0 2021-03-29T00:53:14.675Z
Request End:   7 attempt:0 200 195ms
Request Start: 8 attempt:0 2021-03-29T00:53:15.375Z
Request End:   8 attempt:0 200 218ms
Request Start: 9 attempt:0 2021-03-29T00:53:16.096Z
Request End:   9 attempt:0 200 168ms
✅ Total Sleep between requests, no retry: 7136ms

Approach 1: serial with no sleep

Now we have a function for handling the error and retrying, let's try removing the sleep call from the baseline.

const items = [...10 items...]
for (const item of items) {
  await fetchAndRetryIfNecessary(() => callTheAPI(item))
}

Looks like about 4.7 seconds, definitely an improvement, but not quite at the theoretical level of 3.2 seconds.

⏱️ Running Benchmark Serial with no limits
Request Start: 0 attempt:0 2021-03-29T00:59:01.118Z
Request End:   0 attempt:0 200 327ms
Request Start: 1 attempt:0 2021-03-29T00:59:01.445Z
Request End:   1 attempt:0 200 189ms
Request Start: 2 attempt:0 2021-03-29T00:59:01.634Z
Request End:   2 attempt:0 200 194ms
Request Start: 3 attempt:0 2021-03-29T00:59:01.828Z
Request End:   3 attempt:0 200 177ms
Request Start: 4 attempt:0 2021-03-29T00:59:02.005Z
Request End:   4 attempt:0 200 179ms
Request Start: 5 attempt:0 2021-03-29T00:59:02.185Z
Request End:   5 attempt:0 200 196ms
Request Start: 6 attempt:0 2021-03-29T00:59:02.381Z
Request End:   6 attempt:0 429 10ms
❗ Retrying:   6 attempt:1 at Mon, 29 Mar 2021 00:59:05 GMT sleep for 2609 ms
Request Start: 6 attempt:1 2021-03-29T00:59:05.156Z
Request End:   6 attempt:1 200 167ms
Request Start: 7 attempt:0 2021-03-29T00:59:05.323Z
Request End:   7 attempt:0 200 176ms
Request Start: 8 attempt:0 2021-03-29T00:59:05.499Z
Request End:   8 attempt:0 200 208ms
Request Start: 9 attempt:0 2021-03-29T00:59:05.707Z
Request End:   9 attempt:0 200 157ms
✅ Total Serial with no limits: 4746ms

Approach 2: parallel with no throttling

Let’s try burning through all requests in parallel just to see what happens.

const items = [...10 items...]
const responses = await Promise.all(items.map((item) => (
  fetchAndRetryIfNecessary(() => callTheAPI(item))
)))

This run took about 4.3 seconds. A slight improvement over the previous serial approach, but the retry is slowing us down. You can see the last 4 requests all had to retry.

⏱️ Running Benchmark Parallel with no limits
Request Start: 0 attempt:0 2021-03-29T00:55:01.463Z
Request Start: 1 attempt:0 2021-03-29T00:55:01.469Z
Request Start: 2 attempt:0 2021-03-29T00:55:01.470Z
Request Start: 3 attempt:0 2021-03-29T00:55:01.471Z
Request Start: 4 attempt:0 2021-03-29T00:55:01.471Z
Request Start: 5 attempt:0 2021-03-29T00:55:01.472Z
Request Start: 6 attempt:0 2021-03-29T00:55:01.472Z
Request Start: 7 attempt:0 2021-03-29T00:55:01.472Z
Request Start: 8 attempt:0 2021-03-29T00:55:01.472Z
Request Start: 9 attempt:0 2021-03-29T00:55:01.473Z
Request End:   5 attempt:0 429 250ms
❗ Retrying:   5 attempt:1 at Mon, 29 Mar 2021 00:55:05 GMT sleep for 3278 ms
Request End:   6 attempt:0 429 261ms
❗ Retrying:   6 attempt:1 at Mon, 29 Mar 2021 00:55:05 GMT sleep for 3267 ms
Request End:   8 attempt:0 429 261ms
❗ Retrying:   8 attempt:1 at Mon, 29 Mar 2021 00:55:05 GMT sleep for 3267 ms
Request End:   2 attempt:0 429 264ms
❗ Retrying:   2 attempt:1 at Mon, 29 Mar 2021 00:55:05 GMT sleep for 3266 ms
Request End:   1 attempt:0 200 512ms
Request End:   3 attempt:0 200 752ms
Request End:   0 attempt:0 200 766ms
Request End:   4 attempt:0 200 884ms
Request End:   7 attempt:0 200 1039ms
Request End:   9 attempt:0 200 1158ms
Request Start: 5 attempt:1 2021-03-29T00:55:05.155Z
Request Start: 6 attempt:1 2021-03-29T00:55:05.156Z
Request Start: 8 attempt:1 2021-03-29T00:55:05.157Z
Request Start: 2 attempt:1 2021-03-29T00:55:05.157Z
Request End:   2 attempt:1 200 233ms
Request End:   6 attempt:1 200 392ms
Request End:   8 attempt:1 200 513ms
Request End:   5 attempt:1 200 637ms
✅ Total Parallel with no limits: 4329ms

This looks pretty reasonable with only 4 retries, but this approach does not scale. Retries in this scenario only get worse when there are more requests. If we had, say, 20 requests, a number of them would need to retry more than once—we'd need 4 separate 3 second windows to complete all 20 requests, so some requests would need to retry at best 3 times.

Additionally, the ratelimiter implementation my example server uses will shift the Retry-After timestamp on subsequent requests when a client is already at the limit—it returns a Retry-After timestamp based on the 6th oldest request timestamp + 3 seconds.

That means if you make more requests when you’re already at the limit, it drops old timestamps and shifts the Retry-After timestamp later. As a result, the Retry-After timestamps for some requests waiting to retry become stale. They retry but fail because their timestamps were stale. The failure triggers yet another retry, and causes the Retry-After timestamp to be pushed out even further. All this spirals into a vicious loop of mostly retries. Very bad.

Here is a shortened log of it attempting to make 20 requests. Some requests needed to retry 35 times (❗) because of the shifting window and stale Retry-After headers. It eventually finished, but took a whole minute. Bad implementation, do not use.

⏱️ Running Benchmark Parallel with no limits

...many very messy requests...

Request End:   11 attempt:32 200 260ms
Request End:   5 attempt:34 200 367ms
Request End:   6 attempt:34 200 487ms
✅ Total Parallel with no limits: 57964ms

Approach 3: parallel with async.mapLimit

It seems like a simple solution to the problem above would be only running n number of requests in parallel at a time. For example, our demo API allows 6 requests in a time window, so just allow 6 in parallel, right? Let’s try it out.

There is a node package called async implementing this behavior (among many other things) in a function called mapLimit.

import mapLimit from 'async/mapLimit'
import asyncify from 'async/asyncify'

const items = [...10 items...]
const responses = await mapLimit(items, 6, asyncify((item) => (
  fetchAndRetryIfNecessary(() => callTheAPI(item))
)))

After many 10-request runs, 5.5 seconds was about the best case, slower than even the serial runs.

⏱️ Running Benchmark Parallel with `async.mapLimit`
Request Start: 0 attempt:0 2021-03-29T17:20:42.144Z
Request Start: 1 attempt:0 2021-03-29T17:20:42.151Z
Request Start: 2 attempt:0 2021-03-29T17:20:42.151Z
Request Start: 3 attempt:0 2021-03-29T17:20:42.152Z
Request Start: 4 attempt:0 2021-03-29T17:20:42.152Z
Request Start: 5 attempt:0 2021-03-29T17:20:42.153Z
Request End:   1 attempt:0 200 454ms
Request Start: 6 attempt:0 2021-03-29T17:20:42.605Z
Request End:   6 attempt:0 429 11ms
❗ Retrying:   6 attempt:1 at Mon, 29 Mar 2021 17:20:47 GMT sleep for 4384 ms
Request End:   5 attempt:0 200 571ms
Request Start: 7 attempt:0 2021-03-29T17:20:42.723Z
Request End:   7 attempt:0 429 15ms
❗ Retrying:   7 attempt:1 at Mon, 29 Mar 2021 17:20:47 GMT sleep for 4262 ms
Request End:   2 attempt:0 200 728ms
Request Start: 8 attempt:0 2021-03-29T17:20:42.879Z
Request End:   8 attempt:0 429 12ms
❗ Retrying:   8 attempt:1 at Mon, 29 Mar 2021 17:20:47 GMT sleep for 4109 ms
Request End:   4 attempt:0 200 891ms
Request Start: 9 attempt:0 2021-03-29T17:20:43.044Z
Request End:   9 attempt:0 429 12ms
❗ Retrying:   9 attempt:1 at Mon, 29 Mar 2021 17:20:47 GMT sleep for 3944 ms
Request End:   3 attempt:0 200 1039ms
Request End:   0 attempt:0 200 1163ms
Request Start: 6 attempt:1 2021-03-29T17:20:47.005Z
Request Start: 7 attempt:1 2021-03-29T17:20:47.006Z
Request Start: 8 attempt:1 2021-03-29T17:20:47.007Z
Request Start: 9 attempt:1 2021-03-29T17:20:47.007Z
Request End:   8 attempt:1 200 249ms
Request End:   9 attempt:1 200 394ms
Request End:   6 attempt:1 200 544ms
Request End:   7 attempt:1 200 671ms
✅ Total Parallel with `async.mapLimit`: 5534ms

At 20 requests, it finished in about 16 seconds. The upside is that it does not suffer from the retry death spiral we saw in the previous parallel implementation! But it's still slow. Let's keep digging.

⏱️ Running Benchmark Parallel with `async.mapLimit`
Request Start: 0 attempt:0 2021-03-29T17:25:21.166Z
Request Start: 1 attempt:0 2021-03-29T17:25:21.173Z
Request Start: 2 attempt:0 2021-03-29T17:25:21.173Z
Request Start: 3 attempt:0 2021-03-29T17:25:21.174Z
Request Start: 4 attempt:0 2021-03-29T17:25:21.174Z
Request Start: 5 attempt:0 2021-03-29T17:25:21.174Z
Request End:   0 attempt:0 200 429ms
Request Start: 6 attempt:0 2021-03-29T17:25:21.596Z
Request End:   6 attempt:0 429 19ms
❗ Retrying:   6 attempt:1 at Mon, 29 Mar 2021 17:25:27 GMT sleep for 5385 ms
Request End:   5 attempt:0 200 539ms
Request Start: 7 attempt:0 2021-03-29T17:25:21.714Z
Request End:   7 attempt:0 429 13ms
❗ Retrying:   7 attempt:1 at Mon, 29 Mar 2021 17:25:27 GMT sleep for 5273 ms
Request End:   2 attempt:0 200 664ms
Request Start: 8 attempt:0 2021-03-29T17:25:21.837Z
Request End:   8 attempt:0 429 10ms
❗ Retrying:   8 attempt:1 at Mon, 29 Mar 2021 17:25:27 GMT sleep for 5152 ms
Request End:   1 attempt:0 200 1068ms
Request Start: 9 attempt:0 2021-03-29T17:25:22.241Z

.... more lines ....

❗ Retrying:   17 attempt:2 at Mon, 29 Mar 2021 17:25:37 GMT sleep for 3987 ms
Request Start: 19 attempt:1 2021-03-29T17:25:37.001Z
Request Start: 17 attempt:2 2021-03-29T17:25:37.002Z
Request End:   19 attempt:1 200 182ms
Request End:   17 attempt:2 200 318ms
✅ Total Parallel with `async.mapLimit`: 16154ms

Approach 4: winning with a token bucket

So far none of the approaches have been optimal. They have all been slow, triggered many retries, or both.

The ideal scenario that would get us close to our theoretical minimum time of 3.2 seconds for 10 requests would be to only attempt 6 requests for each 3 second time window. e.g.

Burst 6 requests in parallel
Wait until the frame resets
GOTO 1

The 429 error handling is nice and we will keep it, but we should treat it as an exceptional case as it is unnecessary work. The goal here is to make all the requests without triggering a retry under common circumstances.

Enter the token bucket algorithm. Our desired behavior is its intended purpose: you have n tokens to spend over some time window—in our case 6 tokens over 3 seconds. Once all tokens are spent, you need to wait the window duration to receive a new set of tokens.

Here is a simple implementation of a token bucket for our specific purpose. It will count up until it hits the maxRequests, any requests beyond that will wait the maxRequestWindowMS, then attempt to acquire the token again.

class TokenBucketRateLimiter {
  constructor ({ maxRequests, maxRequestWindowMS }) {
    this.maxRequests = maxRequests
    this.maxRequestWindowMS = maxRequestWindowMS
    this.reset()
  }

  reset () {
    this.count = 0
    this.resetTimeout = null
  }

  scheduleReset () {
    // Only the first token in the set triggers the resetTimeout
    if (!this.resetTimeout) {
      this.resetTimeout = setTimeout(() => (
        this.reset()
      ), this.maxRequestWindowMS)
    }
  }

  async acquireToken (fn) {
    this.scheduleReset()

    if (this.count === this.maxRequests) {
      await sleep(this.maxRequestWindowMS)
      return this.acquireToken(fn)
    }

    this.count += 1
    await nextTick()
    return fn()
  }
}

Let's try it out!

const items = [...10 items...]
const tokenBucket = new TokenBucketRateLimiter({
  maxRequests: 6,
  maxRequestWindowMS: 3000
})
const promises = items.map((item) => (
  fetchAndRetryIfNecessary(() => (
    tokenBucket.acquireToken(() => callTheAPI(item))
  ))
))
const responses = await Promise.all(promises)

With 10 requests it's about 4 seconds. The best so far, and with no retries!

⏱️ Running Benchmark Parallel with a token bucket
Request Start: 0 attempt:0 2021-03-29T01:14:17.700Z
Request Start: 1 attempt:0 2021-03-29T01:14:17.707Z
Request Start: 2 attempt:0 2021-03-29T01:14:17.708Z
Request Start: 3 attempt:0 2021-03-29T01:14:17.709Z
Request Start: 4 attempt:0 2021-03-29T01:14:17.709Z
Request Start: 5 attempt:0 2021-03-29T01:14:17.710Z
Request End:   2 attempt:0 200 301ms
Request End:   4 attempt:0 200 411ms
Request End:   5 attempt:0 200 568ms
Request End:   3 attempt:0 200 832ms
Request End:   0 attempt:0 200 844ms
Request End:   1 attempt:0 200 985ms
Request Start: 6 attempt:0 2021-03-29T01:14:20.916Z
Request Start: 7 attempt:0 2021-03-29T01:14:20.917Z
Request Start: 8 attempt:0 2021-03-29T01:14:20.918Z
Request Start: 9 attempt:0 2021-03-29T01:14:20.918Z
Request End:   8 attempt:0 200 223ms
Request End:   6 attempt:0 200 380ms
Request End:   9 attempt:0 200 522ms
Request End:   7 attempt:0 200 661ms
✅ Total Parallel with token bucket: 3992ms

And 20 requests? It takes about 10 seconds total. The whole run is super clean with no retries. This is exactly the behavior we are looking for!

⏱️ Running Benchmark Parallel with a token bucket
Request Start: 0 attempt:0 2021-03-29T22:30:51.321Z
Request Start: 1 attempt:0 2021-03-29T22:30:51.329Z
Request Start: 2 attempt:0 2021-03-29T22:30:51.329Z
Request Start: 3 attempt:0 2021-03-29T22:30:51.330Z
Request Start: 4 attempt:0 2021-03-29T22:30:51.330Z
Request Start: 5 attempt:0 2021-03-29T22:30:51.331Z
Request End:   5 attempt:0 200 354ms
Request End:   2 attempt:0 200 507ms
Request End:   3 attempt:0 200 624ms
Request End:   4 attempt:0 200 969ms
Request End:   0 attempt:0 200 980ms
Request End:   1 attempt:0 200 973ms
Request Start: 6 attempt:0 2021-03-29T22:30:54.538Z
Request Start: 7 attempt:0 2021-03-29T22:30:54.539Z
Request Start: 8 attempt:0 2021-03-29T22:30:54.540Z
Request Start: 9 attempt:0 2021-03-29T22:30:54.541Z
Request Start: 10 attempt:0 2021-03-29T22:30:54.541Z
Request Start: 11 attempt:0 2021-03-29T22:30:54.542Z
Request End:   8 attempt:0 200 270ms
Request End:   10 attempt:0 200 396ms
Request End:   6 attempt:0 200 525ms
Request End:   7 attempt:0 200 761ms
Request End:   11 attempt:0 200 762ms
Request End:   9 attempt:0 200 870ms
Request Start: 12 attempt:0 2021-03-29T22:30:57.746Z
Request Start: 13 attempt:0 2021-03-29T22:30:57.746Z
Request Start: 14 attempt:0 2021-03-29T22:30:57.747Z
Request Start: 15 attempt:0 2021-03-29T22:30:57.748Z
Request Start: 16 attempt:0 2021-03-29T22:30:57.748Z
Request Start: 17 attempt:0 2021-03-29T22:30:57.749Z
Request End:   15 attempt:0 200 340ms
Request End:   13 attempt:0 200 461ms
Request End:   17 attempt:0 200 581ms
Request End:   16 attempt:0 200 816ms
Request End:   12 attempt:0 200 823ms
Request End:   14 attempt:0 200 962ms
Request Start: 18 attempt:0 2021-03-29T22:31:00.954Z
Request Start: 19 attempt:0 2021-03-29T22:31:00.955Z
Request End:   19 attempt:0 200 169ms
Request End:   18 attempt:0 200 294ms
✅ Total Parallel with a token bucket: 10047ms

Approach 4.1: using someone else's token bucket

The token bucket implementation above was for demonstration purposes. In production, you might not want to maintain your own token bucket if you can help it.

If you're using node, there is a node module called limiter that implements token bucket behavior. The library is more general than our TokenBucketRateLimiter class above, but we can use it to achieve the exact same behavior:

import { RateLimiter } from 'limiter'
class LimiterLibraryRateLimiter {
  constructor ({ maxRequests, maxRequestWindowMS }) {
    this.maxRequests = maxRequests
    this.maxRequestWindowMS = maxRequestWindowMS
    this.limiter = new RateLimiter(this.maxRequests, this.maxRequestWindowMS, false)
  }

  async acquireToken (fn) {
    if (this.limiter.tryRemoveTokens(1)) {
      await nextTick()
      return fn()
    } else {
      await sleep(this.maxRequestWindowMS)
      return this.acquireToken(fn)
    }
  }
}

Usage is exactly the same as the previous example, just swap LimiterLibraryRateLimiter in place of TokenBucketRateLimiter:

const items = [...10 items...]
const rateLimiter = new LimiterLibraryRateLimiter({
  maxRequests: 6,
  maxRequestWindowMS: 3000
})
const promises = items.map((item) => (
  fetchAndRetryIfNecessary(() => (
    rateLimiter.acquireToken(() => callTheAPI(item))
  ))
))
const responses = await Promise.all(promises)

Other considerations

With the token bucket in the two approaches above, we have a workable solution for consuming APIs with rate-limits in production. Depending on your architecture there may be some other considerations.

Success rate-limit headers

APIs with rate-limits often return rate-limit headers on a successful request. e.g.

HTTP: 200
X-Ratelimit-Limit: 40         # Number of total requests in the window
X-Ratelimit-Remaining: 30     # Number of remaining requests in the window
X-Ratelimit-Reset: 1617054237 # Seconds since epoch til reset of the window

The header names are convention at the time of writing, but many APIs use the headers specified above.

You could run your token bucket with the value from these headers rather than keep state in your API client.

Throttling in a distributed system

If you have multiple nodes making requests to a rate-limited API, storing the token bucket state locally on a single node will not work. A couple options to minimize the number of retries might be:

X-Ratelimit headers: Using the headers described above
Shared state: You could keep the token bucket state in something available to all nodes like redis

Verdict: use a token bucket

Hopefully it's clear that using a token bucket is the best way to implement API throttling. Overall this implementation is clean, scalable, and about as fast as we can go without triggering retries. And if there is a retry? You’re covered by the 429 Too Many Requests handling discussed in the beginning.

Even if you don't use JavaScript, the ideas discussed here are transferable to any language. Feel free to re-implement the TokenBucketRateLimiter above in your favorite language if you can’t find a suitable alternative!

Note: check out the example script I used to run these benchmarks. You should be able to use it against your own API by putting your request code into the callTheAPI function.

If you have questions, please do not hesitate to contact us at: developers@useanvil.com.