Connecting a system from its API description

SynaptaGrid7 min read

#integration#api

In short

Connecting an automation to a system that has no ready-made connector usually means typing in each call by hand: the address, the method, the fields it expects. Most modern systems publish an API description, a file in the OpenAPI format that lists every call and the fields each one takes, and a tool that reads it can create those actions for you. The work that remains is yours: choosing which calls you want, supplying the credentials, and testing one call before you rely on it. Check that the description is complete and current, that nothing in it asks for more access than your process needs, and that each imported action does what its name says.

Connect an app and use it in a workflow in SynaptaGrid Automation · 2 min, with captions
Read the transcript

External Systems lists the apps your workflows can use.

Search for the openFDA connector, a public database.

This connector needs no sign-in: the page says so under authentication.

Add a connection and give it a name.

The connection is Connected and Healthy.

The app comes with ready-made activities a workflow can call.

Here is a workflow that uses the connection.

Its middle step calls openFDA to look up reported side effects.

Open the Activities tab and pick that step.

The step uses the openFDA activity, through the connection you just made.

Start it with a drug name: ibuprofen.

The run calls openFDA live.

The run completed, and the answer is kept with it.

The most reported reactions for the drug, straight from openFDA.

What an API description is

An API is the way one program asks another to do something, such as create a customer or fetch an order. An API description is a file, usually in the OpenAPI format, that lists every such call: its address, its method (read, create, change or delete), the fields it takes and what it returns. People call the same file a spec, a Swagger file or an openapi.json.

Many vendors publish one at a fixed address, so you can often find it by adding /openapi.json or /swagger.json to the base address of the API, or by searching the vendor’s developer pages for the words “OpenAPI” or “Swagger”. If a vendor publishes none, you are back to entering calls by hand.

From a description to a usable action

The tool reads the description, you choose which calls to bring in, and each chosen call becomes an action a workflow can use.

The steps, in the order that saves rework

Find the description
Look for the file on the vendor’s developer pages, or try the usual file names on the API’s base address.
Read the list before importing
The preview shows each call with its method and address. Leave out calls your process will never need; fewer actions are easier to review.
Check the risky ones
Calls that delete or change records deserve a second look before anyone can put them in a workflow.
Add the connection
Importing the actions does not supply the system’s credentials. Enter them as a separate step, with the narrowest access the process needs.
Test one call
Run a harmless read first and compare the result with what the system itself shows.
Re-run it when the system changes
Vendors add and change calls. Reading the description again shows what is new or different.

The old way and the new way

The table compares typing each call in by hand with reading the description.

Listing the calls
The old way: Copy each address and method from the vendor’s documentation
The new way: The tool reads the description and lists them
Fields a call expects
The old way: Typed in one at a time, with a typo as the usual failure
The new way: Taken from the description, including which fields are required
Choosing what to bring in
The old way: Whatever someone had time to type
The new way: A preview of every call, with a checkbox for each
When the system changes
The old way: Someone notices a call has stopped working
The new way: Read the description again and see what is new or different
Judgement
The old way: Still yours
The new way: Still yours: which calls, which credentials, which test

How we decided

SynaptaGrid Automation can read an API description when you connect a system. On the system’s page, “Discover APIs” either looks for the description on the system’s base address or takes an address or a file you give it. It then shows a preview of each call it found, with the method, the address and a checkbox, and you import the ones you choose.

We ran it live in November, as the owner of our QA workspace, using a public demo service, the Swagger pet store, as the system. The tool found its description from the base address alone. The preview listed every call in the description as new and selected, and importing them created an action for each. We opened the call that adds a new pet, which sends a request body, and found its fields there: an identifier, a required name, a list of tags, a status and a category. We then deleted the test system.

Three limits of that run, so this guide does not claim more than it showed. We did not run an imported action against the live demo service, so we have not seen a response come back through a workflow. We tested one public description, which is small and tidy; large or unusual descriptions may behave differently. And an earlier run, before a fix, failed to import the calls that send a request body; that is fixed and the run above imported them, but a description with an unusual structure is the first place to look if a call does not come in.

We decided to import actions without credentials and to ask for the connection separately. It means an imported system is not yet able to act, which is the safe state, and it keeps the decision about access with a person.

Standards and accepted practice behind this

These are the practices the guide rests on. We align with them. This page does not claim a certification.

The OpenAPI Specification
An open standard for describing an HTTP API, which is why one tool can read descriptions from many vendors.
Source: OpenAPI Initiative: OpenAPI Specification (opens in a new tab)
Least privilege
Connect with the narrowest access the process needs, and leave out calls it will never use.
Source: NIST glossary: least privilege (opens in a new tab)
Test before you rely on it
Run a harmless call and compare the result with the system itself before building on it.
Review what you import
A person looks at the list of calls, in particular those that change or delete data, before they can be used.

Where SynaptaGrid fits

When a system you need has no ready-made connector, you can still bring it into SynaptaGrid Automation from its API description, then add the connection and use the actions in a workflow.

Check the limits above before you rely on it: whether the vendor publishes a description, whether you have run one imported action end to end, and whether the calls that change data have a person in front of them.

Frequently asked questions

What is an OpenAPI file?
It is a file that describes an API: every call it offers, the method and address of each, and the fields each one takes. It is also called a spec, a Swagger file or an openapi.json.
How do I find the API description for a system?
Look on the vendor’s developer pages for the words OpenAPI or Swagger, or try adding /openapi.json or /swagger.json to the API’s base address. Not every vendor publishes one.
Does importing an API description give access to the system?
No. It creates the list of actions only. You add the system’s credentials as a separate step, and the actions act with that access.
What if some calls do not import?
Check the result of the import, look in the description for unusual structures, import the rest, and add the missing actions by hand.
Share

SynaptaGrid

Bring in a system with no connector

Try it on a test workspace with a system you already use, and import a few calls first.