Connect a web API (REST)

A Web API (REST) connection brings data from a web API into Unity as a snapshot. You describe the API once: where it is, how your key is sent, and which tables to read. Unity reads every table when the connection is refreshed and stores the result; reports read the stored snapshot, so viewing a report never calls the API.

Create one

1. In a report, open Data, choose Add data, then Add a source and New connection.
2. Choose Web API (REST).
3. Name the connection, choose its sign-in (No key or API key), and write its definition in the JSON editor. The editor starts with a World Bank example you can change.
4. Choose Create connection. Every problem in the definition is listed under the editor, each with where it is.
5. If the API needs a key, choose Enter the API key. The credentials page shows where the key will be sent (the base URL); type the key there. The key is never part of the definition, and Unity never shows it again.

An AI assistant can do the same with SaveConnection (type: REST); it reads the format from the connections guide. It never sends the key: it gives you the link where you type it.

The definition

{
  "baseUrl": "https://api.worldbank.org/v2",
  "query": {"format": "json"},
  "tables": {
    "gdp": {
      "path": "/country/US;CN;DE/indicator/NY.GDP.MKTP.CD",
      "query": {"date": "2015:2023"},
      "pagination": {"kind": "page", "pageParam": "page", "sizeParam": "per_page", "pageSize": 1000,
                     "totalPagesPointer": "/0/pages"},
      "records": "/1",
      "columns": {
        "country": {"from": "/countryiso3code", "type": "string"},
        "year": {"from": "/date", "type": "integer"},
        "gdp_usd": {"from": "/value", "type": "decimal", "scale": 2}
      },
      "primaryKey": ["country", "year"]
    }
  }
}

• baseUrl is the https address every request stays under. It is where your key goes.
• auth (for an API key) says whether the key is a query parameter or a header, and its name: {"in": "query", "name": "api_key"}.
• Each table has a path, fixed query parameters, an optional each list (one request series per value, such as several FRED series), pagination (none, offset or page), records (where the list of records is in the response) and columns, each with where its value is (from) and its type.
• Types are exact: string, integer, decimal (with a scale), double, boolean, date, datetime, datetimeOffset, time and json. A value that doesn't fit its type fails the refresh, naming the table, column and record; nothing is rounded.

Test, probe and refresh

Open the connection from Sources (its menu: Web API settings and refresh).

• Test reads the first page of each table and shows a few rows as they would be stored, every problem, and suggested columns from the first record.
• Probe (the connection's owner) sends one request under the base URL and shows the response, your key replaced by [redacted].
• Refresh now reads every table and stores a new snapshot. A refresh is all or nothing: if it fails or you cancel it, nothing is stored and the previous snapshot stays. Run history lists each refresh with its rows and any error.

Then add its tables to the report model like any source: New query, From tables.

Who can do what

The snapshot is the same for everyone who reads the reports that use the connection.

Changing a definition

Changing the base URL, how the key is sent, or the sign-in changes where your key goes. Unity asks you to confirm; it then clears the saved key (you type it again) and stops serving the current snapshot until the next refresh. Removing or retyping a column that a report uses also asks you to confirm, naming the reports you can open.

Safety

Unity sends API requests over https (port 443 or 8443) only, refuses private and internal network addresses, never follows a redirect, reads at most one layer of compression, and never sends your key anywhere but the base URL. When you paste a key, Unity trims spaces around it. Before it stores anything, it checks every value for your key, as it was sent or encoded; a response that carries it fails the refresh. Unity can't recognize a key that the service transforms in other ways, so connect services you trust with your key.

Limits

A refresh that would pass one of these fails, naming the limit, and stores nothing: 10 MB per response, 10,000 pages and 10 million rows per table, an hour per refresh (or 2 minutes with no new page), 50,000 API requests per owner per day, and 10 GB of snapshots per owner. Unity also keeps to the connection's rateLimit (60 requests a minute unless the definition says otherwise). A test or probe has 30 seconds in all. These are Unity's current settings and may change.

For the built-in FRED, World Bank and US Census providers, see Public-data connections. For databases, see Database connections.