Home > Archives > API Requirements for Building a Connector

API Requirements

To add your application as an Azuqua Connector, your API must be able to give Azuqua enough insight into your application to start Flows whenever important changes happen. The most efficient way to do this is through webhook notifications, but Azuqua can also monitor for changes by polling your API for updates on an incremental basis determined by the user’s Azuqua plan.

Additionally, Azuqua needs to be able to replicate common user actions through your API. For example, if users can copy items or link contacts to accounts inside your app, your API should allow Azuqua to do that as well.

Read on for more specific requirements.

All applications:

  1. Your API cannot use session-based authentication. Users need to be able to set up authentications and let them run instead of regularly re-authenticating. We support OAuth 1.0, OAuth 2.0, and Basic Authentication out of the box, but can also support other methods of authentication, so long as they can be easily calculated and attached (headers or query) to a request.
  2. Your API must support field-specific queries of your resources. For example, if your application has a contact resource, the API should allow developers to query for a contact by name and email.
  3. It is best if your API timestamps its records in a standard format (such as Unix/Epoch or ISO8601).
  4. If your API has any file-handling (upload or download, for example), it must conform to standards that would allow users of Node.js to easily use that method.

If your API supports webhooks:

  1. Developers should be able to programmatically set up and tear down webhooks through the API.
  2. All users should have permissions to create webhooks through the API, but the data that triggers the webhook should be scoped to the data that the authenticating user has access to (users should not be able to set up a webhook that monitors resources they can’t access).
  3. There should be a webhook notification for each time a resource is created, modified, or deleted. These notifications should be granular enough that the developer can focus on changes that involve a specific type of resource (but not only a single resource).
  4. The webhook that notifies Azuqua when a certain resource has been modified should also have information about what exactly was changed. For example, if there is a webhook notification for whenever a resource of a certain type is modified, the webhook should include information about which attributes were modified and what the new values of those attributes are.

If your API does not support webhooks:

  1. Developers should be able to query a feed of all the updates that have happened in the authenticated instance of the application, including whenever a record is created, modified, or deleted.
  2. If possible, each update in this feed should have a unique, incrementing ID. When the developers are querying the API, they should be able to pass the ID of the last update they looked at and receive all of the updates that have happened since then. It is also possible to use a timestamp instead of an ID to query for fresh records, but timestamps are not always specific enough and may result in duplicate Flow executions for a single record.
  3. Developers should be able to filter their query by the type of resource they wish to monitor.
  4. Developers should be able to filter their query by the exact type of update that has occurred (e.g. record deleted, name updated, assigned to member, record parent changed, etc.).
  5. If the update that has occurred in the application involves the value of a field being changed, the API should indicate what field was changed and what the new value is.

If your application supports custom resource types:

  1. Developers must be able to query your API for a list of all resource types.
  2. Developers must be able to query your API for the “shape” of each resource type, and get back a list of fields that is possible for the user to edit.

If your application supports custom fields:

  1. Developers must be able to query your API for a list of the custom fields associated with the authenticated instance of the application.
  2. The custom fields should have both a unique identifier and a user-friendly name. It is possible for these two properties to be the same if custom field names are enforced as unique in your application.