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.
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 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.
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.