BroadSQL BroadSQL Downloads
On this page
Documentation / API Client: API sources and configuration

API sources and configuration

An API is defined once, then used from any session: its environments (each with a base URL and variables), its authentication, and its endpoints grouped in folders. You can import the definition from a Bruno collection or build it by hand in CONFIG API, and both ways give the same result.

Importing a Bruno collection

Export your collection from Bruno as a bundled OpenCollection YAML file, a single .yml file (this is the format Bruno itself produces when you choose a single-file export), then import it:

IMPORT API BRUNO "C:\bruno\my-api.yml" MYAPI;

MYAPI is the identifier you choose for this API inside BroadSQL. The command reports what was imported:

API imported: My Service
Environments: created 3, updated 0
Folders: created 12, updated 0
Endpoints: created 87, updated 0

Re-running the same command against an updated export of the same collection is safe: an endpoint, folder, or environment already known from a previous import is updated in place; a new one is added; nothing already imported is ever deleted just because it disappeared from the source file. You never need to re-enter anything by hand.

Directory-based (multi-file) Bruno projects are not read yet, only a single bundled YAML file.

Configuring APIs with CONFIG API

CONFIG API opens a graphical configuration window for the whole API catalog, the same way CONFIG does for database connections, including the same application icon and the same File > Exit menu convention. It is a configuration tool only, never an execution workbench: there is no Execute button, no response viewer, and no request history here. Everything described below can be set up entirely by hand, without ever importing a Bruno file, and everything imported through IMPORT API BRUNO is immediately visible and editable in this same window.

Windows only, and only while connected to $CDF, exactly like CONFIG.

The window is a list of APIs on the left; the selected API's configuration on the right, across five tabs:

  • General: name, description, and (for an imported API) where it came from and when it was last imported.
  • Environments: every environment this API can run against (Development, Staging, Production, and so on), each with its own Base URL and its own variables. Duplicate copies an environment, including its secrets, so the common "duplicate Development, then change the Base URL and credentials" workflow needs no re-entry of everything else.
  • Authentication: the API's default authentication, used by every endpoint that does not set its own and is not inside a folder that sets one.
  • Variables & Headers: API-wide variables and headers, available to every endpoint.
  • Endpoints: a folder tree on the left, with a live search field above it (filters by id, name, alias, folder, verb, or URL as you type; purely a view filter, it never changes or marks anything dirty), and an editor on the right for whichever folder or endpoint is selected. The endpoint editor's General section shows the endpoint's system-managed numeric ID (not editable) alongside its name, method, URL, folder, and alias, so you never need another command just to find the ID that SHOW ENDPOINT and SYNTAX expect: use SHOW ENDPOINT <id> (see Endpoint detail) to look it up from the CLI instead.

One Save for the whole window: API > Save, or Ctrl+S. Editing a field never saves anything by itself; the frame's title shows a trailing * and the Save menu item becomes enabled the moment something is genuinely unsaved, and both clear the instant it is saved. At most one object is ever unsaved at a time: the API-level form (General, Authentication, and Variables & Headers together count as one), the currently selected Environment, or the currently selected Endpoint/Folder, since moving between any two of them (including moving from, say, General to Environments) prompts Save, Discard, or Cancel first whenever the one being left is genuinely dirty. Opening and closing the window, or moving between tabs, untouched never prompts. The menu bar has three menus:

  • API: New, Import..., Delete, then Save (Ctrl+S) and Close.
  • Environment: New, Duplicate, Delete.
  • Endpoint: New Folder, New Endpoint, Delete.

Structural actions (creating a new API, duplicating an environment, deleting anything, importing a Bruno collection) still take effect immediately, exactly as before; only what used to be four separate per-object "Save" buttons became this one Save, so a field edit anywhere in the window is never lost silently and is never saved somewhere you didn't expect.

Renaming a folder or an endpoint from the endpoint tree stages the new name into its editor (marking it unsaved) rather than renaming it immediately: it is persisted the same way any other field edit is, through Ctrl+S/API > Save, or through the Save/Discard/Cancel prompt if you navigate away first.

A secret value (a token, a password, a client secret) is always masked in every table; a "Show values" checkbox reveals it deliberately, the same convention BroadSQL already uses for database passwords.

Creating an API by hand

+ New API asks for an identifier and a name, then creates the API immediately. From there:

  1. Open the Environments tab and create an environment (for example, Production), entering its Base URL.
  2. Open the Authentication tab if the whole API shares one authentication scheme, or leave it set to Inherit/None and configure authentication per folder or per endpoint instead.
  3. Open the Endpoints tab, use New Folder to group related endpoints if useful, then New Endpoint to create one: name, HTTP method, URL (which may reference ${baseUrl} or any other variable), then Ctrl+S (or API > Save).

No internal identifier, source key, or database table is ever exposed; everything is named the way you already name it in the GUI.

Base URL

The environment editor shows Base URL as its own prominent field, never buried in the variable table below it. Internally it is still the ordinary baseUrl variable every endpoint template can reference (${baseUrl}/users), so changing it in the GUI immediately changes what every endpoint in that environment resolves to, whether the endpoint's URL uses ${baseUrl} explicitly or was created as a bare relative path.

Authentication and Inherit versus None

Authentication can be set at three levels: the API itself, a folder, or one endpoint. Inherit means "use whatever the next level up defines" and is the default for a newly created folder or endpoint. None is different: it explicitly turns authentication off at that level, even if a folder or the API above it defines one. The GUI always shows which of the two is in effect; it is never left ambiguous.

Supported types: Basic, Bearer token, API key (header or query), and OAuth2 Client Credentials. An authentication scheme imported from Bruno that this release cannot execute (Digest, NTLM, and similar) is shown as "Unsupported", read only, with the original type named, so it is never silently discarded or misrepresented as "no authentication".

Endpoint aliases

Every endpoint may optionally carry a BroadSQL alias, a short stable name such as DO_ORDER, set in the endpoint's General tab. An alias is entirely separate from the endpoint's display name and from its Bruno import identity:

  • It is never generated automatically, on import or otherwise. You decide which endpoints, if any, get one.
  • It survives a Bruno re-import untouched, even when the re-import updates the endpoint's name, URL, method, or anything else about it.
  • It must be a valid identifier (letters, digits, and underscores, not starting with a digit) and must be unique within the API it belongs to. The same alias may be reused by a different API (for example, PINGMAIL can name one endpoint in DESK and an unrelated endpoint in CRM at the same time), since an alias is always looked up within one API: the active session's API, or the one named explicitly with API <apiId> in SHOW ENDPOINTS.
  • Deleting the endpoint frees its alias immediately for reuse elsewhere, even within the same API.

An alias is a discovery handle, not something RUN accepts: RUN takes a URL (see Running an endpoint (RUN) below). SHOW ENDPOINT, SYNTAX and HELP accept the alias in place of the numeric endpoint id, and TAB after RUN expands it to the endpoint's URL. It also exists for a possible future scripting statement that would call a configured endpoint by this name (for example, a future CALL DO_ORDER(...)); that statement does not exist yet in this release.

Importing and exporting Bruno YAML

Import Bruno YAML and Export Bruno YAML, at the bottom of the API list, do the same thing as IMPORT API BRUNO and the export described below, with a preview before import and a scope/secret choice before export.

Exporting to Bruno YAML

An API configured in BroadSQL, whether imported from Bruno or built entirely by hand, can be exported back to a real bundled OpenCollection YAML file that Bruno itself can open, through CONFIG API's Export Bruno YAML button (there is no separate CLI export command in this release). You choose which environments to include (all, by default) and whether to include secret values.

Secret values are excluded by default. A secret variable, header, or credential is written to the file without its value at all, never as an empty string and never as a fake masked value standing in for the real one; every non-secret part of the configuration exports normally. Including real secret values requires explicitly turning that on and confirming a warning that the file will then contain plaintext credentials.

An explicit None authentication round-trips correctly. Setting None (as opposed to leaving it on Inherit) exports as an explicit "no authentication" entry and comes back as None on re-import, never as an unrecognized/unsupported type: Inherit and explicit None remain distinguishable throughout.

The BroadSQL alias is never exported. OpenCollection has no field for it, and BroadSQL does not invent one, to avoid producing a file that looks like standard Bruno YAML but is not. An alias assigned in BroadSQL therefore survives a re-import into the same BroadSQL installation, but not a round trip through an exported file into a different installation.

A structured request body (form-urlencoded or multipart form data) is edited and re-exported as its underlying data rather than through a dedicated field-by-field table in this release; every field, value, and piece of metadata is still preserved exactly, only the editing experience is plainer than a purpose-built table would be.

If an imported endpoint's authentication cannot be represented exactly in OpenCollection (an unsupported type such as Digest), the export still proceeds and clearly lists which endpoint's authentication could only be approximated, rather than silently producing a file that looks correct but is not.

Environments

Every environment defined in the Bruno collection (Development, Staging, Production, ...) becomes a separate, selectable environment in BroadSQL. The same imported endpoint resolves differently depending on which environment you execute it under; changing environment never changes the endpoint definition itself.

SHOW API ENVIRONMENTS MYAPI;

lists every environment as a table:

+----+-------------+---------------------------------+
| ID | NAME        | BASE URL                         |
+----+-------------+---------------------------------+
| 1  | Development | https://dev.example.com          |
| 2  | Production  | https://api.example.com          |
+----+-------------+---------------------------------+
2 environments

Environment variables that are secret (tokens, client secrets, ...) are never displayed by any command.

Example: define a source by hand

  1. On Windows, CONNECT $CDF; then CONFIG API;, and API > New: identifier ORDERS, name Order service.
  2. Environments tab: New, name Development, Base URL https://dev.example.com.
  3. Authentication tab: Bearer token ${TOKEN}, with TOKEN defined as a secret variable of the environment.
  4. Endpoints tab: New Endpoint, method GET, URL ${baseUrl}/orders/:id, then Ctrl+S.

SHOW API ENVIRONMENTS ORDERS; then lists Development, and CONNECT API ORDERS:Development; is ready to run it (see Running API requests).