Call a Data API from an Application

Every published data API is an HTTP endpoint. An application or a script calls it with the account's API key, with no browser session.

The request

• URL: the DataIQ address followed by /api/v1/data/<connection name>/<api name>. The Data APIs page shows each API's path, and its OpenAPI document gives the server address.
• Key: send the account's API key in the x-api-key header. Create one under API Keys in the account settings.
• Query and stored procedure APIs: POST with a JSON body {"params": {"NAME": value}}, using the parameter names the API lists. A positional {"args": [value, ...]} array, in parameter order, is accepted instead. Sending both is refused.
• CRUD APIs: with <base> for /api/v1/data/<connection>/<name> and <key> for the row's primary key: list with GET <base>, read with GET <base>/<key>, create with POST <base>, update with PUT <base>/<key>, and delete with DELETE <base>/<key>.

POST /api/v1/data/<connection>/accounts-by-currency
x-api-key: <account API key>
Content-Type: application/json

{"params": {"CURRENCY": "EUR"}}

The response

{
  "name": "accounts-by-currency",
  "connectionName": "<connection>",
  "version": 1,
  "url": "/api/v1/data/<connection>/accounts-by-currency",
  "columns": [
    {"name": "ACCOUNT_ID", "type": "VARCHAR2"},
    {"name": "BALANCE", "type": "NUMBER"},
    {"name": "CURRENCY", "type": "VARCHAR2"}
  ],
  "rows": [
    ["1001", "1500.32", "EUR"],
    ["1002", "2884.78", "EUR"]
  ],
  "rowCount": 2,
  "updateRowCount": null,
  "out": {}
}

• columns and rows: the result set. Each row lists its values in column order, as text.
• rowCount: the rows returned, at most the configured row limit.
• updateRowCount: the rows an INSERT, UPDATE, DELETE or MERGE changed, and null for a read.
• out: a procedure's output values by parameter name, as JSON. An object type comes back as a JSON object, a function's value as RETURN, and any further result set under its name.

A stored procedure with an object output parameter answers with its values under out:

"out": {
  "STATUS_CODE": null,
  "EMP": {"FIRST_NAME": "Jane", "LAST_NAME": "Doe", "SALARY": 24000}
}

Errors

An error answers with a status code and a JSON body {"error": "<message>"}. The messages below are examples for an API named accounts-by-currency on a connection named sales-db.

Status	When	Message
400	Both an API key and a bearer token were sent	Send either x-api-key or an Authorization bearer token, not both.
401	No API key and no signed-in session	Unauthorized
401	The key is unknown or revoked	Invalid or revoked API key.
404	No API with that name and method on the connection	No POST data API accounts-by-currency on connection sales-db.
422	A parameter name or count does not match	Unexpected parameter(s): currency_code. Accepted names: CURRENCY.
422	The database refused the statement	The database's own message, for example an ORA- error

Good to know

• API keys are accepted when DataIQ runs with OL Hub. A standalone server refuses a key with 401, and callers sign in instead.
• The key never appears in an OpenAPI document or in a response.
• Each API's own OpenAPI document, from OpenAPI in the success dialog, can generate a client for it.