On this page

Documentation / API Client: Running API requests

Running API requests

Running a request has two steps: choose the API and environment once with CONNECT API, then send requests with RUN and a relative URL, the way you would type paths against a live server. SHOW ENDPOINTS, SHOW ENDPOINT and SYNTAX help you find what to run.

Connecting to an API session

CONNECT API MYAPI:Development;

establishes an active API session context, independent of and coexisting with any SQL database connection:

API MYAPI connected using environment Development.

Once connected, RUN and SHOW ENDPOINTS (below) use this API and environment without repeating them on every command, though both also accept an explicit API <apiId> clause to target a different API without an active session at all (see below). CONNECT API never closes or replaces the current database connection; connecting to a database with CONNECT <id> never clears an active API context either: the two are entirely independent, exactly like BroadSQL's connection and login concepts already are for SQL alone.

The prompt shows both when both are active:

$CDF [API MYAPI:Development]>

and just the API context when no database connection is active:

[API MYAPI:Development]>

An unknown or inactive API/environment, or a malformed <api>:<environment> target (a missing colon, a missing API name, or a missing environment name), is refused with a clear message; the previous API context, if any, is left unchanged.

Deactivating the currently connected API afterward (through CONFIG API, in another window) does not clear the session context by itself, but it does not remain usable through it either: RUN and `SHOW ENDPOINTS` revalidate the API's active status on every call and refuse it, naming it as inactive. DISCONNECT API and reconnect once it has been reactivated.

DISCONNECT API;

clears only the active API session context. The database connection, if any, is completely unaffected:

$CDF [API MYAPI:Development]> DISCONNECT API;

$CDF>

If no API context is active, DISCONNECT API does nothing.

Browsing endpoints

SHOW ENDPOINTS;

lists every endpoint of the active CONNECT API context, as a compact catalog table:

+----+------+----------------+------------------+--------+
| ID | VERB | FOLDER         | NAME             | ALIAS  |
+----+------+----------------+------------------+--------+
| 5  | GET  | Users          | Get User         |        |
| 6  | POST | Users          | Create User      |        |
| 12 | GET  | Users / Search | Advanced Search  | SEARCH |
+----+------+----------------+------------------+--------+
3 endpoints

A long folder path, name, or alias may be shown ellipsized (...) in this catalog view for display only: the persisted value itself is never truncated. Use SHOW ENDPOINT <id> (below) to see any one endpoint's full detail, or SHOW ENDPOINTS MATCH <keyword> to find it. This table is deliberately compact: it no longer shows the URL or whether the verb is executable, though both remain visible either way (SHOW ENDPOINT <id> for the full URL, Supported HTTP methods for which verbs can execute).

Without an active API context, add API <apiId> to target that API directly, no session required:

SHOW ENDPOINTS API MYAPI;

Both forms accept the same optional filters, in either order, after API <apiId> (or first, when it is omitted):

SHOW ENDPOINTS VERB GET;
SHOW ENDPOINTS MATCH search;
SHOW ENDPOINTS VERB GET MATCH search;
SHOW ENDPOINTS API MYAPI VERB GET MATCH search;

VERB <verb> matches the HTTP method exactly, case-insensitively. MATCH <keyword> is a case-insensitive substring search across the folder path, name, and alias combined. A filter that matches nothing reports an empty result, never an error.

Every HTTP method is listed, regardless of whether it can execute; see Supported HTTP methods. An endpoint is never hidden merely because its verb isn't executable. The ID column (not the endpoint's display name, which is not guaranteed unique across folders) or, if one is set, the ALIAS column, is what you pass to SHOW ENDPOINT or SYNTAX; to run the endpoint, use its URL with RUN.

Endpoint detail (SHOW ENDPOINT)

SHOW ENDPOINT 5;
SHOW ENDPOINT PINGMAIL;
SHOW ENDPOINT findAll;

(ENDPOINT and SHEND are accepted as shorter synonyms for SHOW ENDPOINT.) The argument accepts a numeric id (global and unique across every API, no active CONNECT API session needed; the same resolver SYNTAX and HELP <alias> use), an alias, or a name (the latter two scoped to the active session's API). A name matching more than one endpoint is reported as an ambiguous-candidates table (ID | METHOD | FOLDER | NAME | ALIAS | PATH) instead of being guessed at; use the id or alias shown there instead.

The command shows one endpoint's complete detail as a vertical, plain-text view: top-level properties as plain Label : value lines, then a blank line and each populated section (Query parameters, Path parameters, Headers, Authentication), with only the individual entries inside a section prefixed - :

ID          : 5
API         : My Service
Folder      : Users
Name        : Get User
Alias       : (none)
Method      : GET
URL         : ${baseUrl}/users/${userId}

Query parameters
- expand : ${expand}   disabled

Path parameters
- userId : ${userId}   enabled

Headers
- Accept : application/json

Authentication: Inherited

URL is the composed effective URL: the endpoint's base path plus every currently enabled query parameter (see Query parameters and the URL below). A disabled parameter never appears there, only in the "Query parameters" section with its own disabled marker, its definition still fully visible. A value flagged secret in CONFIG API is masked (******) here too, in both the composed URL and its own row, the same masking convention used everywhere else. Authentication names the type in effect (or Inherited), never a resolved credential value.

Executing an endpoint

RUN is URL-native: you connect to an API/environment once with CONNECT API, then run one or more relative URLs against that session, exactly the way you would type paths against a live server:

CONNECT API MYAPI:Development;
RUN /users/42;

resolves the URL, query and path parameters, headers, and request body (see Request bodies below) against the connected environment, matches it to the corresponding stored endpoint (for its authentication, headers, and body; see Running an endpoint (RUN) below for exactly how matching works), sends the request, and displays the result. By default the response is shown as a complete LIST view (see Result display: LIST and TABLE below):

API: My Service
Environment: Development
Endpoint: GET Get User

GET https://dev.example.com/users/42

HTTP 200
Duration: 143 ms
Content-Type: application/json

id   : 42
name : Alice

A non-JSON textual response (plain text, HTML, XML) is shown as-is. A response BroadSQL cannot safely display as text is shown as size/content-type metadata only, never as raw bytes. Any HTTP status is displayed the same way: a successful write commonly returns 200, 201, 202, or 204, and a 204 No Content (typical for DELETE) is shown cleanly with no body section, never as an error. An HTTP error response (404, 401, 500, ...) is shown exactly like a successful one: the status and body are what you came to see. BroadSQL never confuses a real HTTP response, whatever its status, with a transport/network failure (a connection refused, a DNS failure, a timeout), which is reported separately and always before any status/body could exist.

If a value the request needs (a variable, a path segment) cannot be resolved, execution stops before any network request is made, naming exactly what is missing, unless that value belongs to a disabled query parameter, which is never resolved or sent at all (see Query parameters and the URL).

Request bodies

A POST/PUT/PATCH endpoint (or a DELETE endpoint that happens to need one) sends whatever body is configured for it in CONFIG API, interpolated through the same variable scope as the URL, query, path, and headers:

{
  "name": "${CUSTOMER_NAME}",
  "email": "${CUSTOMER_EMAIL}"
}

executes with ${CUSTOMER_NAME}/${CUSTOMER_EMAIL} replaced by their resolved values, exactly like everywhere else ${variable} is used: see Variables. BroadSQL substitutes the configured text; it does not parse or rebuild the body as a JSON object, so the result is exactly what the substitution implies. If an interpolated value happens to make the body invalid JSON (for example, a value containing an unescaped "), BroadSQL still sends it as configured, the same textual-substitution behavior already used for URLs and headers, not a new validation layer, and the server's own response reports the problem.

Only a body configured as plain JSON, text, XML, or a SPARQL query can currently be sent; this is what CONFIG API's Body tab calls the json/text/xml/sparql modes. A structured body (form-urlencoded or multipart-form) is stored and preserved losslessly (round-trips through Bruno import/export and remains editable in CONFIG API) but cannot be executed yet, see Executing an unsupported method or body. CONFIG API's structured-body editor remains the raw canonical JSON text described in Configuring APIs with CONFIG API; this release does not add a field-by-field editor for it.

A request body is entirely optional: an endpoint with no body configured sends none, regardless of its HTTP method. DELETE commonly has none, but a POST/PUT/PATCH with nothing configured sends none too, and a GET with a body configured (unusual, but not prevented) would send it. BroadSQL follows what is configured, not a stereotype about the verb.

If no Content-Type header is already configured, BroadSQL sets a sensible default for the body's mode (application/json, text/plain, application/xml, or application/sparql-query); an explicit, configured Content-Type header always takes precedence.

The request body itself is never echoed anywhere in BroadSQL's own output, only the response is shown, so a secret value resolved inside a body is sent to the server correctly but never appears on screen, in a log, or in generated documentation.

Running an endpoint (RUN)

RUN is the single command that executes an endpoint, and it is URL-native, not id/alias-based: it always takes a relative URL, matched against the currently connected API/environment, never an explicit API/ENV clause of its own.

RUN [HTTP_METHOD] <relative-url> [TABLE|RAW];

CONNECT API <api>:<environment>; must be run first; RUN fails with a clear message (No API is connected. Use CONNECT API <api>:<environment>; before RUN.) if nothing is connected, and there is no way to name a different API/environment for a single RUN call; reconnect first. Within that session:

CONNECT API MYAPI:Development;
RUN /users/42;
RUN DELETE /users/42;

HTTP_METHOD is optional and defaults to GET; any other configured method (DELETE, POST, PUT, PATCH, HEAD, OPTIONS, ...) is given explicitly, before the URL. The URL is matched against the connected API's stored endpoints by method and path shape (so ${baseUrl}/users/:id matches /users/42) to find the endpoint whose authentication, headers, and body configuration apply; there is no separate step to look up an id or alias first. An endpoint's id, alias (set in CONFIG API), or name is a completion/discovery shortcut only, never something RUN itself accepts as a target: RUN SEARCH; or RUN listActiveUsers; (a bare reference, not a URL) is rejected with a hint toward SYNTAX SEARCH; (to see the endpoint's actual URL shape; see Endpoint detail) or typing RUN SEARCH<TAB>/RUN listActiveUsers<TAB> when JLine completion is active (see activatejline), which expands the reference to its real URL before you run it. Most imported endpoints never have an alias set at all, only a name and a numeric id, and completion works from any of the three.

A :name path or query placeholder, and any literal segment, resolves the same way described in Scope and precedence below, including a ${name}/{{name}} reference typed directly in the URL itself, which now resolves against the connected API's active environment before endpoint matching even happens (so it can affect which endpoint a URL matches, not just the request sent to it). The optional trailing TABLE/RAW clause selects the response rendering, exactly as described above; the default remains a complete LIST view. Authentication, variable resolution, result rendering, and DUMP API RESULT capture all behave the same way regardless of the endpoint's method or shape.

Query parameters and the URL

An endpoint's URL and its structured query-parameter list (both editable in CONFIG API's endpoint editor, and both visible in SHOW ENDPOINT <id>) are two views of the same request, kept in sync in both directions:

URL
${baseUrl}/products?limit=${limit}&expand=${expand}

Query parameters
limit   ${limit}    enabled
expand  ${expand}   enabled

Disabling a parameter removes it from the displayed URL immediately, without deleting its definition:

URL
${baseUrl}/products?limit=${limit}

Query parameters
limit   ${limit}    enabled
expand  ${expand}   disabled

Re-enabling it restores it to the URL. Editing the URL text directly works the other way: adding &sort=${sort} adds a new, enabled sort row to the parameter grid; changing limit=${limit} to limit=50 updates that row's value to 50; and **removing a parameter from the URL text disables the matching row rather than deleting it**, symmetric with the Enabled checkbox, so its definition and value are never lost by an accidental edit. Editing the URL and editing the parameter grid always stay consistent with each other: the composed URL displayed anywhere (the editor, SHOW ENDPOINT <id>) can never contradict what the structured parameters say is enabled.

A disabled query parameter is never resolved, validated, or sent. This is what makes disabling a parameter safe even when no value for it exists anywhere:

expand = ${expand}, disabled     -- execution succeeds; ${expand} is never looked up
expand = ${expand}, enabled      -- execution fails: "Unable to resolve variable: expand" (if ${expand} is undefined)

An enabled parameter behaves exactly like any other ${variable} reference: if it cannot be resolved, execution stops before any network request, naming the missing variable.

Executing a write method

A POST/PUT/PATCH/DELETE endpoint executes exactly like a GET, using its configured method, request body, and headers:

CONNECT API MYAPI:Development;
SHOW ENDPOINTS VERB POST MATCH customer;

+----+------+-----------+-----------------+----------------+
| ID | VERB | FOLDER    | NAME            | ALIAS          |
+----+------+-----------+-----------------+----------------+
| 21 | POST | Customers | Create Customer | CREATECUSTOMER |
+----+------+-----------+-----------------+----------------+
1 endpoint

RUN POST /customers;

API: My Service
Environment: Development
Endpoint: POST Create Customer

POST https://dev.example.com/customers

HTTP 201
Duration: 118 ms
Content-Type: application/json

id     : 501
status : created

The request body configured for the matched Create Customer endpoint (for example {"name": "${CUSTOMER_NAME}"}) was interpolated and sent, exactly as described in Request bodies. Updating or removing the same resource works the same way, only the matched endpoint's own configured method/path/body changes what is sent:

RUN PATCH /customers/501;

PATCH https://dev.example.com/customers/501

HTTP 200
Duration: 96 ms
...

RUN DELETE /customers/501;

DELETE https://dev.example.com/customers/501

HTTP 204
Duration: 74 ms

Executing an unsupported method or body

RUN OPTIONS /users;

against an OPTIONS-method endpoint refuses cleanly, before any request reaches the target server:

Execution refused.

Method OPTIONS is not enabled for execution in this release.

The same happens for an endpoint whose body mode is form-urlencoded or multipart-form (see Request bodies):

Endpoint 'Upload Attachment' has a 'multipart-form' request body, which this release cannot execute
(only json/text/xml/sparql bodies can be sent). The endpoint and its body remain fully visible and
editable in CONFIG API.

In both cases, the endpoint stays fully visible and configurable in the catalog and in CONFIG API; only execution is refused.

Executing an inactive API, endpoint, or environment

Deactivating an API or an environment (via CONFIG API) leaves it fully visible for configuration/reactivation, but refuses RUN, naming it as inactive rather than as not found:

API 'MYAPI' is inactive. Reactivate it first (CONFIG API), or use SHOW ALL APIS to list active APIs.

Environment 'Development' for API 'MYAPI' is inactive. Reactivate it first (CONFIG API), or use
SHOW API ENVIRONMENTS MYAPI to check its status.

An inactive endpoint is different: since RUN matches a URL structurally against the connected API's endpoints (see Running an endpoint (RUN)), a deactivated endpoint is simply excluded from matching, exactly as if it did not exist:

No endpoint matches:
  /customers/501

Use SHOW ENDPOINTS API MYAPI to see configured endpoints for this API.

Reactivate it from CONFIG API, or with the endpoint's Reactivate action, and RUN matches it again normally, provided its alias, if it has one, has not since been claimed by a different active endpoint (see "Endpoint aliases" above); a reactivation that would create a duplicate alias is refused the same way a conflicting save would be, leaving the endpoint inactive. SHOW ENDPOINT <id>/SYNTAX <id>, by contrast, can still look up an inactive endpoint by its numeric id directly; only RUN's URL matching excludes it.

API Client overview
Parameters, variables and authentication: how :name, ${name} and VAR values are found.
Working with API results: the LIST, TABLE and RAW displays, and exporting the result.
Command reference: CONNECT, DISCONNECT, RUN, SHOW ENDPOINTS, SHOW ENDPOINT, SYNTAX.