Use any web API

Most web services publish a description of themselves: an OpenAPI (Swagger) file, or a GraphQL schema. Switchboard reads it and makes one step per operation, with a form built from the operation's own parameters, so you pick Get a repository instead of writing an http step by hand.

Add an API #

In the app, choose Window > Imported Steps, then Add > Web API…; or in Terminal:

switchboard api add https://petstore3.swagger.io/api/v3/openapi.json --name petstore
switchboard api add https://api.example.com/graphql --graphql --name example
switchboard api add http://localhost:8000/openapi.json --name myapp

The last one is a program of your own running on this Mac (FastAPI and others serve this file by default). OpenAPI 3.0, 3.1 and Swagger 2, as JSON. A YAML spec needs converting first (yq -o=json spec.yaml > spec.json).

Then look in the Add step picker: the API's steps are grouped under its name, and the search box finds them by what they do.

Sign in #

If the spec says the API needs a token, a key or a password, Switchboard tells you. Store it in the Keychain, with the Key… button in Imported Steps, or from the clipboard or a pipe, never typed into a macro:

pbpaste | switchboard api auth petstore

The secret is added to each request when it runs and never appears in a trace. A macro you share carries no secret.

What a step does #

It builds the request from the form, sends it through the same path as the http step, and returns the parsed JSON, so later steps can read its fields. A failing status (400 and up) fails the step with the server's message. A step in a dry run is simulated and sends nothing.

When the API changes #

switchboard api refresh reads the spec again. Steps whose operation is gone are kept and marked stale ("Operation removed from petstore") so a macro that used one says why it can't run.