API Integrations

1. API Authorization

Engineers need to understand the API provider’s authorization protocol before connecting to their API. For example, an API provider may require OAuth2 authorization for connection.

2. Understanding API provider’s documentation

One of the most common complaints about a third party’s API from engineers is poor documentation. Poor documentation hinders engineers’ progress on their applications. Poor documentation slows down the process of building new integrations.

3. Maintenance

Once the integration is built, an engineer needs to handle maintenance and upgrading. Any changes made to the product’s functionality can mess up the entire process of accessing or manipulating data.

  • Authentication type changing
  • Endpoints being added, modified, or removed
  • Changing the data returned by endpoints

Building a Single integration

In the simplest scenario, building a single API integration will look something like the diagram below, and the integration must address the same challenges mentioned earlier.

Building multiple API integrations

Engineering teams spend significant effort building one integration, and their product will more than likely have multiple integrations.


During my time at Poindexter Inc., we wanted to launch a new product called Gridabl and move their existing customers from their legacy product to Gridabl and integrate with the following applications quickly

  • Xero
  • Quickbooks
  • Facebook
  • Stripe
  • Google Analytics
  • Salesforce

Past decisions made

In the past, our team previously built a SaaS application called Poindexter, which is integrated with Xero.

1. Authorization

Our team needed to understand the OAuth2 authorization workflow to integrate with Xero, and we faced some challenges.

Poindexter’s Token Refresh Workflow

  1. If the access token is set to expire soon, Poindexter sends a requests to Xero’s authorization server with a refresh token for a new access token.
  2. With the new access token, Poindexter makes a request to Xero’s resource server for a protected resource

2. Documentation

Our team spent significant time understanding Xero’s documentation and how it fits into the application. There was also some difficulty getting the answers we needed as we are located in different countries.

3. Maintenance

Our team would maintain the integration with Xero, and if anything went wrong, we needed to fix it immediately. As mentioned above, maintenance adds more time working on the integration, and our responsibility is to make sure that the integration is working smoothly.

Lessons learned

We wanted to avoid the same mistakes with Gridabl and did not want to go through the challenges of integrating multiple APIs. We needed a way to integrate APIs quickly and abstract the challenges of building API integrations.


We decided to use an Integration as a platform tool to accomplish this objective. We evaluated different tools based on cost, functionality, security, and usability.

Integrating with APIs using Paragon Connect

The Paragon ConnectAPI handles the challenges of building integrations such as understanding documentation, maintenance, and authorization.

  1. The user requests a Paragon user token from the server, and the Paragon user token is needed to access Paragon’s ConnectAPI.
    (API is built in Ruby on Rails)

Challenge faced with Paragon

Paragon has limited documentation, which made it a little bit difficult to translate, and if we had any questions related to the tool, there weren’t many resources online to help resolve the issue since the company is very young.


To recap about API Integrations, here are some points to remember

  • Integrating APIs allows applications to share data and communicate with each other freely
  • The most common challenges of integrating APIs are API authorization, understanding documentation, and maintaining API integrations
  • Understanding the API provider’s documentation
  • Authorization to access APIs
  • Maintaining API Integrations
  • Engineering teams will have to face the same challenges every time they integrate a new API
  • Integration as a Platform tools such as Paragon abstract away all of the challenges of integrating APIs, so that engineers can focus on other tasks
  • The advantage to integrating directly with APIs is that data trust and technical trust can be ensured


  1. https://www.krit.com/blog/custom-integrations-are-a-total-headache-heres-why-theyre-worth-it
  2. https://www.saastr.com/the-top-saas-companies-have-an-average-of-350-integrations/
  3. https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2
  4. https://www.quora.com/What-are-the-difficulties-in-API-integration
  5. https://www.quora.com/How-difficult-is-it-to-integrate-a-web-API-and-whats-the-process-you-take-when-you-integrate-an-API-What-challenges-do-you-face
  6. https://www.useparagon.com/blog/6-things-you-should-never-build-in-your-saas#integrations
  7. https://api2cart.medium.com/what-does-it-take-to-build-an-api-integration-c73f5ec88d45
  8. https://developers.google.com/identity/protocols/oauth2/web-server#uri-validation
  9. https://blog.cloudrail.com/bad-api-documentation-why-and-what-you-can-do-about-it/
  10. https://www.pandium.com/blogs/3-best-practices-for-api-documentation



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store