Building an API to work with Integry

You've figured out the integration usecase you want to build with Integry. If you're looking to pull data inside your app, you must provide an API that Integry will use to create, update, or delete objects at your end. .

For example, if you want to import tasks from Asana, you will need an equivalent API endpoint in your app for creating tasks (or tickets, todos, items, or the matching name in your app). 

Ideally, you may already have an API. But if you don't, here are some best practices and recommendations below. If you're looking to push data from your app, you don't need an API, please check out App Actions for more

There have been many great articles written on building Restful APIs. This document is only a subset of recommendations that are relevant to integrations.

Authentication Best Practices

We recommend API-key or Basic Auth. The key should ideally be scoped to a per-user level. Integry will use this key to make calls to your app's API on the user's behalf. You can also have API keys scoped at an app level. These keys are usually for admin APIs, where Integry can change any user's object. 

Don't make an Integry-specific endpoint

The number of API clients using your APIs will increase as you grow. Creating client-specific endpoints will quickly go out of hand. Instead, we recommend creating generic endpoints you can give anyone, not just Integry. 

🟢 good: /api/task

🔴 bad: /projects/integry

Don't hardcode third-party apps

A key benefit of working with Integry is that it will allow you to pull data from any app. You may start with one app like Asana, but if you need to add another app, you will have to code another endpoint, which will quickly become unwieldy. So:

🟢 good: /api/task

🔴 bad: /api/asana

Ideally, your logic should be agnostic of the third-party app you're integrating with (unless you plan on building a product around the app). It shouldn't matter where the data comes from. However, if you need to track where it comes from, Integry can send its internal app ID and name in your API call.

Return values

APIs that create objects should return the ID of the created object at the minimum and, ideally, the entire object. This is helpful for downstream steps in your integration.