Connect an API — Sterodata docs

Add an API under Settings, import its OpenAPI or WSDL description, choose how it signs in, and pick which of its lists become tables.

Connecting an API lets Sterodata read lists from another system, such as customers, orders or invoices, and keep them as tables in your workspace. Sterodata calls each list a resource. The same connection can also hold actions: the changes the API accepts, which you can run from buttons. You need to be a workspace admin.

Before you start

Find the API's address (its base URL), and if it has one, the address of its description: an OpenAPI (Swagger) file in JSON or YAML, or a WSDL file for a SOAP service.
If the API asks for a key, a token or a login, have it ready, or save it first under Credentials.
The API must be reachable from the internet. Addresses on a private network are refused, and an API that needs a credential must use https://.

Add the connection

Open Settings and choose the Integrations tab. Choose Add integration (or Add API endpoint when the list is empty).
Answer How do you want to configure this integration?
- Import from OpenAPI spec: for an OpenAPI 3 description in JSON or YAML.
- Import from WSDL (SOAP): its operations become resources and actions.
- Custom REST API (manual): you enter the address and sign-in now, and add resources and actions later.
For an import, paste the description's address in Spec URL and choose Import spec. Otherwise choose Next.
Check Name and Base URL. An import fills them in when the description names them.
Under Authentication, pick a Credential: No authentication (public API), one you saved, or + Save new credential…, which saves a bearer token.
Choose Review after an import, or Create for a manual connection.
In the review, tick the resources and actions to keep. Select all and Unselect all help when a description lists many. Open a resource to see its Schema (pick the column that identifies a row), its Pagination and its Sync parameters. A required parameter must have a value before Create works. Each action can be moved to another resource, or kept as Workspace-wide. Read the Warnings: they are the guesses the import made.
Choose Create.

Everything is saved in one go: if any part is refused, nothing is saved and you see the reason. Sterodata then sends a test request and says whether it worked.

How it signs in

Credential	What Sterodata sends
No authentication	Nothing. For public APIs.
Bearer token	The token, in the `Authorization` header of every request.
API key	The key, in a header you name (for example `X-API-Key`).
Basic auth	No header. Its username and password go into the request only where an automation's step puts them (Credential · username, Credential · password), as SOAP services that take a login inside each request expect.

The tables it fills

Each resource you keep becomes a table in the workspace's built-in database, in a sidebar folder named after the connection. The table is made by the resource's first sync: see Keep a table in sync.

Values you set in a resource's Sync parameters (a date range, a login, a filter) are used when an automation's HTTP read step reads the resource. The resource's own schedule and Sync now do not use them, and a resource with a required parameter fails there. Keep such a resource in sync with an automation.

Change it later

Open the connection under Integrations. Its page has three tabs:

General: Transport, Base URL, Auth, Credential, Rate limit (requests per minute) and Timezone.
Resources: Add resource, and for each one Sync now, Configure schema (primary key), Configure pagination, Configure parameters and Delete resource.
Actions: Add action, and the actions it holds. See Buttons that run an API action.

Action log, at the top, lists recent calls of its actions.

To rename or delete a connection, use the menu beside its name in the side list. Deleting it stops its syncs; the tables it filled stay in the workspace as ordinary tables that people can edit.