Introducing Pizzly - an open-sourced, free, fast & simple API Integrations Manager
Tags: news, webdev, node, showdev
Published: 2020-09-14 08:07:30

Within my company, Bearer, the whole team is focused on helping developers that rely on third-party APIs. In 2019, our engineers developed a solution that eased how to integrate with any API that uses OAuth.

It saved hours of engineering time when working with API integrations, by handling both the authentication strategy (with refresh tokens) as well as proxying the request.

As we believe no developers should ever have to spend hours dealing with the ins and outs of integrating OAuth API, we’ve decided to fully open-source our tool. Introducing [Pizzly: The OAuth Integration Proxy](https://github.com/bearer/pizzly).

{% github bearer/pizzly no-readme %}

## **What is Pizzly?**

[Pizzly](https://github.com/Bearer/Pizzly) is an OAuth Integrations Manager. It provides everything a developer needs to easily consume an OAuth-based API (_aka an API that uses OAuth as the authentication method_).

Most APIs now use the [OAuth framework](https://oauth.net/) to authorize an application that wants to access a user's data. One of the main reasons is that OAuth provides the best user experience while being very secure. But one thing has been totally forgotten in the OAuth framework: the developer experience.

It is much more difficult for a developer to use an OAuth based API than it is to use an API that relies on an API Key. Try timing yourself on how long it takes to integrate with two APIs. Let's see how long it takes to have your first successful request to the Stripe API compared to the Google Sheets API.

![Time To First API Call (TTFAC) without Pizzly](https://blog.bearer.sh/content/images/2020/07/ttfac-without-pizzly.png)
<figcaption>Time To First API Call (TTFAC) without Pizzly</figcaption>

It took me around 43 minutes and 19 seconds to perform an authenticated request to Google Sheets starting from scratch ([source](https://gist.github.com/Frenchcooc/aa39ca7001975d23b8f5db4b046fc1cc)). And only 5 minutes for Stripe ([source](https://gist.github.com/Frenchcooc/32dfc8a2dbbd5a3acb54e8e705d958a7)). **We should change that.**

Pizzly aims to provide the best developer experience when using an OAuth-based API. One of its power-features is that it completely handles the OAuth-dance (including refreshing a token), meaning a developer can focus on requesting endpoints without spending hours dealing with authentication.

Here's the same test using Pizzly:

![TTFAC with Pizzly](https://blog.bearer.sh/content/images/2020/07/ttfac-with-pizzly.png)
<figcaption>Time To First API Call (TTFAC) with Pizzly</figcaption>

It took me almost the same amount of time (5 min vs 7 min) to perform an authenticated request to the Google Sheets API compared with Stripe, starting from scratch with Pizzly. Again, here's the [source](https://gist.github.com/Frenchcooc/4c75ac43d0cb0da3a550ffccf85cf4e5). And contrary to the previous test, using Pizzly means the token will be refreshed once expired.

## **How does it work?**

Pizzly provides multiple tools to help developers with their API integrations, including:

-   an auth service - _to handle the OAuth-dance_;
-   a proxy - _to make authenticated requests to an API_;
-   a dashboard - _to enable and configure APIs_;
-   a JS library - _to connect a user from your frontend._

The two major services are Auth and Proxy:

1.  The auth service handles the OAuth-dance and generates what is called an `authId` each time a user has successfully authorized your OAuth application. The `authId` acts as a reference to the OAuth payload (i.e. `access token` and `refresh token`). While the access token and refresh token expire and change over time, the authId is always the same. Think of it as something like a user identity.
2.  The proxy service forwards HTTP requests to the third-party APIs. To authenticate the request, the developer sends the `authId` alongside. This tells the proxy service to transform the request and authenticate it with the right access token. In case it has expired, Pizzly will refresh the token and retry the request.

Another great tool that Pizzly brings is the dashboard.

![Pizzly dashboard](https://blog.bearer.sh/content/images/2020/07/pizzly-dashboard.jpg)

The dashboard lets you configure your integrations, test them, and look at what's happening.

## **How to use it?**

Pizzly is self-hosted, meaning you can install it on your machine or any platform-as-a-service (e.g. Heroku, AWS, etc.). Here's a guide on [how to get started](https://github.com/Bearer/Pizzly#getting-started).

Once installed, enable an API from the list and trigger a complete OAuth-dance in a few lines of code using the Pizzly JS library:

```jsx
// Initialize Pizzly
const pizzly = new Pizzly({ host: "pizzly.example.org" }) 
const api = pizzly.integration('api')

// Connect a user to an API
api
  .connect()
  .then(({ authId }) => console.log("Sucessfully connected!", authId))
  .catch((error) => console.error("It failed!", error))
```

When a user is successfully connected, you retrieve an `authId` that you can use to make authenticated requests to the API. Here's a cURL on how to make a request to the Google Sheets API to create a spreadsheet on the user's drive:

```bash
curl -X POST /proxy/google-sheets/ \\
 -H "Pizzly-Auth-Id: REPLACE-WITH-YOUR-AUTH-ID"
```

No matter what your backend is running on (Ruby, Go, Node.js), send your requests to the proxy. It makes integrating APIs much faster. You can even perform your calls from your frontend, with the [JS client](https://github.com/Bearer/Pizzly/tree/master/src/clients/javascript).

## **Some demo**

Some great project are already using Pizzly to handle the API requests:

* [Airtable Shipping Block](https://github.com/picsoung/airtable-shipping-block)
* [Push to Google Sheets](https://dev.to/bearer/how-to-integrate-with-the-google-sheets-api-in-2-minutes-569o)
* GitHub fetch profile (tutorial) in [React](https://dev.to/frenchcooc/how-to-make-api-calls-in-react-g1e) or [Vue.js](https://dev.to/bearer/how-to-use-an-oauth-based-api-in-vue-js-1elo)

_Psst._ At [Bearer.sh](https://www.bearer.sh), Pizzly is a full part of our API integrations flow, to manage Slack notifications for example.

## **How it can help you?**

![https://raw.githubusercontent.com/Bearer/Pizzly/master/views/assets/img/docs/pizzly-preconfigured-apis.jpg](https://raw.githubusercontent.com/Bearer/Pizzly/master/views/assets/img/docs/pizzly-preconfigured-apis.jpg)

Pizzly supports more than 50 APIs out-of-the-box. All you need to do is set your credentials and scopes in the dashboard. This list includes the most common APIs, such as:

-   **Communication APIs**: Gmail, Microsoft Teams, Slack, Zoom;
-   **CRM**: Front, Hubspot, Salesforce, etc.
-   **Developer tools**: BitBucket, GitHub, GitLab, etc.
-   **Finance APIs**: Xero, Sellsy, Zoho Books, etc.
-   **Productivity**: Asana, Google Drive, Google Sheets, Jira, Trello, etc.
-   **Social APIs**: Facebook, LinkedIn, Reddit, etc.
-   **[and more...](https://github.com/Bearer/Pizzly/wiki/Supported-APIs)**

But that's not all. Each pre-configured API is a `.json` file located [within the `/integrations/` folder](https://github.com/Bearer/Pizzly/tree/master/integrations). So if you want an API that is not pre-configured yet, you can set up the configuration as a new `.json` file within that directory. If ever you feel like sharing, create a new PR to share your own configuration with the community.

## **Built with**

- Node.js ⚡️
- [Passport.js](http://www.passportjs.org/) - To handle the OAuth dance 🕺
- [Knex](http://knexjs.org/) - To manage requests to the database 📃
- [EJS](https://ejs.co/) - For the dashboard templating ⚙️
- Vanilla JavaScript - For some magic 🍦

## **Support us**

[Star the repo on GitHub](https://github.com/Bearer/Pizzly), Tweet, share among your friends, teams and contacts!

You can also get in touch directly with me via email at corentin@bearer.sh or on Twitter @frenchcooc. And if you really want to help us make Pizzly better, [contribute to the GitHub repo](https://github.com/Bearer/Pizzly)!