Attracting New Integrations By Simplifying Your API

Using an API Gateway, we're able to onboard API partners with relative ease while having the flexibility to safely update our applications.

Attracting New Integrations By Simplifying Your API

With a top-notch set of integrations, your product becomes an even more important part of the workflows your customers rely on. To get and retain those integrations, you must have a public API that’s developer-friendly and expandable. As your application grows and changes, you’ll want to add functionality to (or otherwise reorganize) its API as well. With every breaking change, though, you risk losing the developers that use your API and, critically, their integrations that your customers might be relying on.

It might simply not be worth the time for a partner to rewrite their integration if your endpoints keep changing!

So "measure twice, cut once" is critical here — especially for the first version of your API, when you’re still building trust with external developers. At Riskalyze, since advisors actively use many of our integrations as a core part of their day-to-day, we decided to make working with future versions of our API simpler by adding a gateway server in front of our API.

Simplifying Your API

Working in fintech, I’ve seen APIs that required pages of documentation just to understand the simplest operations.

By simplifying your API, you encourage developers to try an integration with your product instead of your competitor's.

When you start building your API, it may look similar to the diagram below. In this example, we have a single API server that our partners can connect their app to. Authorization is handled by, and all objects are returned from, this one server.

This works well for a simple API, but what if your product expands and you need to split your public API amongst a group of API microservices? In this example, we've created an auth microservice, a client microservice, and a portfolio microservice. We could introduce a breaking change into our API by requiring all of our API partners to update the URLs used for each service. Instead of the simple diagram above, we’d need to give our API partners the more complex diagram below.

There’s got to be a better way! What if we could abstract out the complexity of our API's infrastructure and make future changes without breaking existing integrations? With a small proxy service we can proxy all of the API requests from our API partners to the correct microservice — all while providing them the same easy-to-understand endpoints with the same base URL.

While at first glance this may look more complex, any external developers only ever need to know about the top two lanes (Partner App and API Gateway). That’s exactly the same as the original diagram we started with!

By using a proxy server for your public API, you can make major changes to your internal architecture without requiring new development from, or creating breaking-change-downtime for, your existing API partners.

What if you already have an existing API? You can still set up a proxy service. Simply set up routes in the proxy service to point to your existing API endpoints. Once you have launched the proxy service, point the URL of the existing API to the proxy service.

Under The Hood

Let's take a look at what this setup might look like. We're using the Express framework as a base for our gateway service and proxying our requests with HttpProxy. We've added in a few more dependencies to our actual server, but HttpProxy has a good example of a basic proxy server.

We chose Node.js for our API Gateway because of its low overhead and speed, but there are many other good options out there. Choose a programming language that you’re comfortable with that supports a high number of concurrent threads.

Step 1: Resolve Your Routes

Let's assume that your API already exists at https://api.example.com/v1 with endpoints for /auth, /clients and /portfolios. Your new microservices live at https://auth.example.com/v1, https://clients.example.com/v1, and https://portfolios.example.com/v1. You will need to store those relationships in either a database or code. Is this the first version of your API? You can use the same routes to provide the same basic-API-like endpoints to the developers using your API.

Step 2: Handle Any Scoping or Permissions

This is likely in addition to any app-level permissions or scopes. Apply your own business logic needs as required, but you'll want to at least have access controls for your different services handled here. For example, if a given API partner cannot access your portfolio endpoints, they should not be able to hit the portfolio microservice.

Step 3: Proxy Requests

Now that you've resolved your routes and handled any permission issues, it's time to proxy the request to a microservice. We can do that using the following code:

function proxy(req, res, microservice_route) {
	proxyServer = HttpProxy.createProxyServer({});
	proxyServer.web(req, res, {
		target: microservice_route
	});
}

Step 4: Documentation

If you haven't already documented your API, now is the time while everything is still fresh in your memory. Having good API documentation will further encourage others to choose your product for an integration they may be developing. It will also allow you to focus on building the next great addition to your API or product instead of spending that time on API support.

Wrapping It Up

Using an API Gateway, we're able to onboard API partners with relative ease while having the flexibility to safely update our applications. While advisors love our product on its own, we've strengthened those relationships by having a number of well-used integrations. As we continue to move to microservices, we have an easy way to increment our API to newer versions, and a clear path forward to scale our API without introducing breaking changes.