Connections Guide

What is a connection?

Connections are the glue that integrates your Gadget app with third-party systems. They can model and extract data from those systems into your Gadget app, allowing you to build reports around that data or react to changes. Connections also allow your app to perform actions on the remote API, such as sending emails with SendGrid or publishing a product on Shopify.

Why should you care about connections?

Although standalone applications can provide utility, most software we build needs to integrate with external systems to provide business value. GitHub integrates with your continuous integration system so that you get feedback on pull requests. Commerce software integrates with warehouse management systems to track inventory.

Second, building a reliable integration is difficult, and quite repetitive. Once you get past properly authenticating your app, there are lots of issues one has to address when talking to the external system. Webhooks are unreliable, so how do I ensure my system always has the most up-to-date data? Similarly, communicating over the network is unreliable, so how do I make actions reliable? How do I respond to specific changes in state? These are just a few of the things one has to manage when building an integration.

Finally, some remote APIs can be difficult to model. For example, Shopify products have many variants as child resources. If you want to model products and product variants separately in your app, you also need to deal with the fact that a product variant being deleted results in a product update payload, with a variants list containing all variants except the one that was deleted.

What do connections provide?

Gadget connections provide all the things you need to reliably integrate with external systems. There are three major types of things you get when installing a connection on your Gadget app:

  1. Data modeling: Gadget will provide models with some connections, and ensure these models are kept up to date with the remote system, through webhooks and background data synchronization.
  2. Effects: For third-party systems which provide APIs that allow you to run actions on remote systems, such as sending an email, Gadget will provide effects that allow you to easily perform those actions.
  3. Client: When Gadget doesn’t do exactly what you need, an authenticated client is available for your custom code effects to use.