JSON (API)
Last updated
Last updated
Sometimes you need to visualize data not contained in an RDBMS or NOSQL data store, but available from some HTTP API. For those times, the application provides the JSON data source.
The application treats all incoming data from the JSON data source as text; so you should be prepared to use table formatting when rendering the data.
The application treats all incoming data from the JSON data source as text; so you should be prepared to use table formatting when rendering the data.
Use the JSON Data Source to query arbitrary JSON API’s. Setup is easy because no authentication is needed. Any RESTful JSON API will handle authentication through HTTP headers. So just create a new Data Source of type JSON and name it whatever you like (“JSON” is a good choice).
The application will detect data types supported by JSON (like numbers, strings, booleans), but others (mostly date/timestamp) will be treated as strings (unless specified in ISO-8601 format).
This Data Source takes queries in YAML format. Here’s some examples using the GitHub API:
Return a list of objects from an endpoint
This will return the result of the above API call as is.
Return a single object
The above API call returns a single object, and this object is being converted to a row.
Return Specific Fields
In case you want to pick only specific fields from the resulting object(s), you can pass the fields option:
Return an inner object
Many JSON API’s return arrays of nested objects. You can access an object in an array with the path key.
The above query will use the assignee objects from the API result as the query result.
Pass query string parameters
You can either craft your own URLs, or you can pass the params option:
The above is the same as:
Additional HTTP Options
You can pass additional keys to modify various HTTP options:
method - the HTTP method to use (default: get)
headers - a dictionary of headers to send with the request
auth - basic authentication username/password (should be passed as an array: [username, password])
params - a dictionary of query string parameters to add to the URL
data - a dictionary of values to use as request body
json - same as data except that it’s being converted to JSON
You can use existing data sources created with this type, but you can’t create new ones. We recommend migrating to the JSON data source type.
The URL data source expects your endpoints to return JSON with a special data structure (see below).
The body of your query will include only the URL that returns data, for example:
To manipulate the data (filter, sort, aggregate etc.) you can use the Query Results Data Source.
The returned object must expose two keys: columns and rows.
The columns key should expose an array of javascript objects describing the columns to be included in your data set. Each object will include three keys:
name
type
friendly_name
rows should return an array of javascript objects representing each row of data. The keys for each object should match the name keys described in your columns array.
The following data types are supported for columns:
text
integer
float
boolean
string
datetime
date
An example of returned data appears below:
