A powerful and intuitive UI for data reporting

Programmatically integrate with Reflect's data reporting and visualization platform

Although Reflect provides a powerful and intuitive user interface for its data reporting and visualization platform, some use cases require a more programmatic and less UI-driven approach. Reflect thus offers a REST API that enables you to securely manage Reflect projects, views, database connections, data models and more.

Security

We take many measures to ensure that your data is safe as it transits Reflect services.

All traffic through Reflect services is encrypted using TLSv1.2. Any non-encrypted traffic is automatically redirected to the appropriate encrypted channel.

Authentication

All HTTP calls to the Reflect REST API require you to provide a Reflect API token as the password component of a basic auth header. You do not need to provide a username in this header. Here’s an example:

$ curl -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/projects'

You can fetch, create, and delete API tokens in the Reflect app.

Read-only API tokens

By default, API tokens that you create can be used to perform any action available through the REST API. If you’d like to provide a token with read-only API access, you can click READ ONLY? in the tokens interface:

Once you’ve done that, the token can be used for actions such as listing projects, fetching data models, or fetching database connection metadata, but cannot be used to, for example, create a project or delete a view.

Resources

The Reflect REST API is highly resource based, with most calls revolving around managing these resources for your account:

• Reflect projects are collections of views that visualize your data. You can create as many projects and views as you want.

  Both projects and views are referred to using slugs, such as your-project-1 or your-view-1. All project and view slugs must be unique for your account (you will receive errors if you try to create a project or view with a slug that’s already taken).

• To produce visualizations, Reflect pulls in your data via secure database connections and presents that data using data models. You can create as many database connections and data models as you’d like on any Reflect plan.
• Parameter sets enable you to “impersonate” your users by passing pre-defined user parameters to the API.
• Key pairs, consisting of an access_key and a secret_key are assigned to each project and used for authenticating views.
• Reflect Agents talk to both your database (using connection info that you provide) and the Reflect REST API itself. Agents can be hosted by Reflect or you can run your own Agent (or a cluster of Agents) on your own infrastructure.

Projects

A project contains any number of views that you’ll use when you want to embed in your application. Each project has a corresponding data model.

Project actions available through the API

• List all projects
• Create a project
• Show a project
• Update a project
• Delete a project
• List recent statements
• Associate a connection
• Show a project’s data model

Example project object

{
  "name": "Your Project #1",
  "slug": "your-project-1",
  "description": "The very first project that you created with the API.",
  "created_at": "2016-02-04t00:18:07.817442z",
  "updated_at": "2016-02-07t01:35:22.223042z"
}

List all projects

List all of the projects that are currently associated with your Reflect account. This endpoint will return a list of project objects.

Example request and JSON response body

$ curl -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/projects'

[
  {
    "name": "Your Project #1",
    "slug": "your-project-1",
    "description": "Your very first project created with the API.",
    "created_at": "2016-02-04t00:18:07.817442z",
    "updated_at": "2016-02-07t01:35:22.223042z"
  }
]

Create a project

Create a new project for your Reflect account. You must specify two things when creating a new project: a name for the project (which can include spaces and special characters) and a slug.

Optionally, you can supply a connections parameters as an array of strings, each of which represents a connection slug.

Example request and JSON request body

$ curl XPOST \
  -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  --data-binary @./project.json \
  'https://api.reflect.io/v1/projects'

The curl example above assumes that you have this JSON stored in a project.json file:

{
  "name": "Your Project #1",
  "slug": "your-project-1",
  "connections": ["your-connection"]
}

Example JSON response body

{
  "name": "Your Project #1",
  "slug": "your-project-1",
  "description": "Your very first project created with the API.",
  "created_at": "2016-02-04t00:18:07.817442z",
  "updated_at": "2016-02-07t01:35:22.223042z"
}

Show a project

Fetch information about a specific project using the project’s slug.

Example request and JSON response body

$ curl -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/projects/your-project-1'

{
  "name": "Your Project #1",
  "slug": "your-project-1",
  "description": "Your very first project created with the API.",
  "created_at": "2016-02-04t00:18:07.817442z",
  "updated_at": "2016-02-07t01:35:22.223042z"
}

Update a project

Update a project.

Example request and JSON response body

$ curl -XPUT -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  --data-binary @./project.json \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/projects/your-project-1'

{
  "name": "Your Project #1",
  "slug": "your-project-1",
  "description": "Your very first project created with the API.",
  "created_at": "2016-02-04t00:18:07.817442z",
  "updated_at": "2016-02-07t01:35:22.223042z"
}

Delete a project

Delete a project (identified by project slug).

Example request

$ curl -XDELETE \
  -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/projects/your-project-1'

List recent statements

List statements that have been run for this project in descending order (by the time at which they were created). Statements are paginated at 10 statements per page. You can request a different page by passing the page parameter. By default, the first page is returned.

The runtime attribute is the length of time that it took to run the query in milliseconds. The status column can be one of success and failed.

Example request and JSON response body

$ curl -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/projects/your-project-1/statements?page=1'

[
  {
    "statement": "SELECT \"users\".\"email\" AS \"Email\", COUNT(\"users\".\"id\") AS \"Count\" FROM \"users\" AS \"users\" GROUP BY \"Email\"",
    "runtime": 9,
    "status": "success",
    "created_at": "2016-04-06T11:26:02.212968-07:00",
    "updated_at": "2016-04-06T11:26:02.212968-07:00"
  },
  {
    "statement": "SELECT \"users\".\"email\" AS \"Email\", COUNT(\"users\".\"id\") AS \"Count\" FROM \"users\" AS \"users\" GROUP BY \"Email\"",
    "runtime": 17,
    "status": "success",
    "created_at": "2016-04-06T11:08:24.749929-07:00",
    "updated_at": "2016-04-06T11:08:24.749929-07:00"
  }
]

Associate a connection

Associate a connection with a project. The server will download the connection’s metadata and update the project’s data model accordingly.

The API endpoint returns the complete data model. If the connection is already associated with the project, a 412 Precondition Failed error will be returned.

Example request and JSON response body

$ curl -u -XPOST \
  ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  --data-binary @./connection.json \
  'https://api.reflect.io/v1/projects/your-project-1/connections'

{
  "slug": "your-connection-1"
}

Example JSON response body

{
  "name": "Example Project",
  "slug": "example-project",
  "description": "An example project and data model.",
  "data_sets": [
    {
      "name": "example_data_set",
      "connection": "your-connection-1",
      "tables": [
        {
          "table": "table1",
          "primary_key": "id",
          "columns": {
            "column1": "text"
          }
        }
      ]
    }
  ],
  "fields": {
    "Field 1": {
      "data_set": "example_data_set",
      "table": "table1",
      "columns": ["column1"]
    },
    "Field 2": {
      "data_set": "example_data_set",
      "table": "table1",
      "columns": ["column2"]
    }
  },
  "created_at": "2016-02-22T14:31:41.57292-08:00",
  "updated_at": "2016-02-22T14:31:41.57292-08:00"
}

Show a project’s data model

Fetch the data model associated with a project (identified by slug).

Example request and JSON response body

$ curl -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/projects/your-project-1/data-model'

{
  "slug": "orders",
  "name": "Order Project Example",
  "description": "An example project and data model for a fictitious ecommerce store.",
  "data_sets": [
    {
      "name": "orders",
      "credential": "reflect-connection-1",
      "tables": [
        {
          "table": "orders",
          "columns": {
            "order_date": "time",
            "order_priority": "text"
          }
        }
      ]
    }
  ],
  "fields": {
    "Order Date": {
      "data_set": "orders",
      "table": "orders",
      "columns": ["order_date"]
    }
  }
}

Database connections

The Reflect API keeps a record of which database connection credentials live in different Reflect Agents that you’ve deployed. The API endpoints documented here are useful for figuring out which connections Reflect knows about.

Connection metadata is automatically forwarded to the Reflect API by Reflect agents. Database connection info isn’t handled by the Reflect REST API. Only the bare essential metadata is kept for each database connection, in the name of limiting the security surface area of our API. All sensitive database connection information, including usernames, passwords, and IP addresses are encrypted and stored within Reflect Agents.

Database connection actions available through the API

• List all connections
• Show connection metadata
• Refresh connection metadata

Connection objects

Database connection objects consist of just a few pieces of metadata:

Example connection object

{
  "slug": "test-connection-1",
  "name": "Your Test Connection",
  "driver": "postgres",
  "updated_at": "2016-03-01T20:34:10.407359-08:00",
  "created_at": "2016-03-01T20:34:10.407359-08:00"
}

List all connections

List all of the connections that have been forwarded to the Reflect API by agents that you’re managing. This list will also include any connections that you’ve registered with a Reflect-hosted agent.

Example request and JSON response body

$ curl -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/connections'

[
  {
    "slug": "test-connection-1",
    "name": "Test Connection",
    "driver": "postgres",
    "updated_at": "2016-03-01T20:34:10.407359-08:00",
    "created_at": "2016-03-01T20:34:10.407359-08:00"
  }
]

Show connection metadata

Instructs the agent to inspect the database and gather the relevant metadata about tables and relationships between them. It also introspects the data type for each column and classifies it accordingly. How a given column’s data type is classified is dependent upon the database driver.

Relationships are inferred based on foreign key configuration in the database. If no foreign key constraint is configured between tables then a relationship cannot be inferred.

Example request and JSON response body

$ curl -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/connections/test-connection-1/metadata'

{
  "name": "your_database",
  "connection": "test-connection-1",
  "tables": [
    {
      "table": "your_table",
      "columns": {
        "column1": "number",
        "column2": "text"
      }
    }
  ]
}

Refresh connection metadata

Instructs the agent to fetch new schema information and updates the available tables and fields. This will be reflected across all projects that use this connection.

Example request and JSON response body

$ curl -XPOST -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  'https://api.reflect.io/v1/connections/test-connection-1/metadata/refresh'

{
  "name": "your_database",
  "connection": "test-connection-1",
  "tables": [
    {
      "table": "your_table",
      "columns": {
        "column1": "number",
        "column2": "text",
        "column3": "text"
      }
    }
  ]
}

Parameter sets

A project can have multiple pre-defined parameter sets. Parameter sets let you “impersonate” your users in the Reflect app so that you can get a sense for how a given view will look or behave when it’s deployed.

If a project has at least one parameter set, the Reflect app will require that you use a parameter set when editing a view.

Parameter set actions available through the API

• List parameter sets
• Create a parameter set
• Show a parameter set
• Update a parameter set
• Delete a parameter set

Example parameter set object

{
  "name": "Parameter Set #1",
  "slug": "parameter-set-1",
  "parameters": [
    {
      "field": "Your Field #1",
      "op": "=",
      "value": "abc123"
    }
  ],
  "created_at": "2016-04-21T17:57:11.332755Z",
  "updated_at": "2016-04-21T17:57:11.332755Z"
}

List parameter sets

List all the parameter sets associated with this project. If no parameter sets exist then an empty array will be returned.

If a parameter set exists, the Reflect app will require that you use a parameter set when editing a view.

Example request and JSON response body

$ curl -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/projects/your-project-1/parameter-sets'

[
  {
    "name": "Parameter Set #1",
    "slug": "parameter-set-1",
    "parameters": [
      {
        "field": "Your Field #1",
        "op": "=",
        "value": "abc123"
      }
    ],
    "created_at": "2016-04-21T17:57:11.332755Z",
    "updated_at": "2016-04-21T17:57:11.332755Z"
  }
]

Create a parameter set

Creates a new parameter set and associates it with the project. The slug for the parameter set must be unique. If the slug is not unique, a 412 Precondition Failed error will be returned from the API with details.

Example request and JSON request body

$ curl -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  --data-binary @./parameter-set.json \
  'https://api.reflect.io/v1/projects/your-project-1/parameter-sets'

{
  "name": "Parameter Set #1",
  "slug": "parameter-set-1",
  "parameters": [
    {
      "field": "Your Field #1",
      "op": "=",
      "value": "abc123"
    }
  ]
}

Example JSON response body

{
  "name": "Parameter Set #1",
  "slug": "parameter-set-1",
  "parameters": [
    {
      "field": "Your Field #1",
      "op": "=",
      "value": "abc123"
    }
  ],
  "created_at": "2016-04-21T17:57:11.332755Z",
  "updated_at": "2016-04-21T17:57:11.332755Z"
}

Show a parameter set

Gets a parameter set associated with the project. If the parameter set does not exist, a 404 Not Found error will be returned.

Example request and JSON response body

$ curl -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  'https://api.reflect.io/v1/projects/your-project-1/parameter-sets/parameter-set-1'

{
  "name": "Parameter Set #1",
  "slug": "parameter-set-1",
  "parameters": [
    {
      "field": "Your Field #1",
      "op": "=",
      "value": "abc123"
    }
  ],
  "created_at": "2016-04-21T17:57:11.332755Z",
  "updated_at": "2016-04-21T17:57:11.332755Z"
}

Update a parameter set

Updates an existing parameter set. Only the name and parameters fields are updatable. Updates to the slug, created_at, and updated_at fields will be ignored.

If the parameter set does not exist a 404 Not Found error will be returned.

Example request and JSON request body

$ curl -XPUT \
  -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  --data-binary @./parameter-set.json \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/projects/your-project-1/parameter-sets/parameter-set-1'

{
  "name": "Parameter Set #1",
  "parameters": [
    {
      "field": "Your Field #1",
      "op": "=",
      "value": "abc123"
    }
  ]
}

Example JSON response body

{
  "name": "Parameter Set #1",
  "slug": "parameter-set-1",
  "parameters": [
    {
      "field": "Your Field #1",
      "op": "=",
      "value": "abc123"
    }
  ],
  "created_at": "2016-04-21T17:57:11.332755Z",
  "updated_at": "2016-04-21T17:57:11.332755Z"
}

Delete a parameter set

Deletes a parameter set specified by name associated with a project specified by slug. If the parameter set is successfully deleted, the API will return the parameter set you just deleted.

Example request and JSON response body

$ curl -XDELETE \
  -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  'https://api.reflect.io/v1/projects/your-project-1/parameter-sets/parameter-set-1'

{
  "name": "Parameter Set #1",
  "slug": "parameter-set-1",
  "parameters": [
    {
      "field": "Your Field #1",
      "op": "=",
      "value": "abc123"
    }
  ],
  "created_at": "2016-04-21T17:57:11.332755Z",
  "updated_at": "2016-04-21T17:57:11.332755Z"
}

Key Pairs

A project has one or more key pairs associated with it. These key pairs are used for generating signed requests so you can use Reflect in multi-tenant environments.

Key pair actions available through the API

• List project key pairs

Example key pair object

{
  "access_key": "b5cb8544-07ed-11e6-a66b-cfb440724ccd",
  "secret_key": "fc14a940-07ed-11e6-9608-e3ab6109c04d",
  "created_at": "2016-04-21T17:57:11.332755Z",
  "updated_at": "2016-04-21T17:57:11.332755Z"
}

List project key pairs

List all the key pairs that have been generated for this project. The JSON for each project will always include both the secret key and the access key.

Example request and JSON response body

$ curl -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/projects/your-project-1/key-pairs'

[
  {
    "access_key": "b5cb8544-07ed-11e6-a66b-cfb440724ccd",
    "secret_key": "fc14a940-07ed-11e6-9608-e3ab6109c04d",
    "created_at": "2016-04-21T17:57:11.332755Z",
    "updated_at": "2016-04-21T17:57:11.332755Z"
  }
]

Agents

Reflect uses agents to communicate with your database. You can run the Reflect Agent yourself and register it with the Reflect APIs or you can use a Reflect-hosted version of the agent.

All communication with databases goes through a Reflect agent. Reflect can host the agent for you, or you can install the agent in your infrastructure.

Agents automatically register themselves with the Reflect API when they first come online.

Agent actions available through the API

• List all agents
• Update an agent
• Add a connection to an agent
• Update a connection
• Test a connection

Example agent object

{
  "id": 1,
  "name": "agent #1",
  "url": "http://192.168.50.101:9700",
  "created_at": "2016-02-04t00:18:07.817442z",
  "updated_at": "2016-02-07t01:35:22.223042z"
}

List all agents

List all of the agents registered with your Reflect account. This list also includes agents hosted by Reflect.

Example request and JSON response body

$ curl -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/agents'

[
  {
    "id": 1,
    "name": "agent #1",
    "url": "http://192.168.50.101:9700",
    "created_at": "2016-02-04t00:18:07.817442z",
    "updated_at": "2016-02-07t01:35:22.223042z"
  }
]

Update an agent

Update the metadata associated with an agent. You can modify the agent’s name and/or the agent’s url Before the metadata is saved, the API will test to make sure that the connection can be established.

If a connection cannot be established, an error will be returned.

Example request

$ curl -XPUT \
  -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Your Updated Agent", "url": "http://10.0.10.11:9700"}' \
  'https://api.reflect.io/v1/agents/1'

Example JSON response body

[
  {
    "id": 1,
    "name": "agent #1",
    "url": "http://192.168.50.101:9700",
    "created_at": "2016-02-04t00:18:07.817442z",
    "updated_at": "2016-02-07t01:35:22.223042z"
  }
]

Add a connection to an agent

The Reflect API can add connections directly to specific agents on your behalf. The API will keep record of the connections that are on the agent. Anything in the options object is stored securely on the agent and not stored by the API in any way.

Example request and JSON request body

$ curl -XPUT \
  -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  --data-binary @./connection.json \
  'https://api.reflect.io/v1/agents/1/connections'

{
  "name": "Your Connection",
  "slug": "your-connection",
  "driver": "postgres",
  "options": {
    "host": "your.host.com",
    "port": "5432",
    "user": "your_user",
    "password": "your_password",
    "database": "your_database",
    "ssl": "require"
  }
}

Example JSON response body

{
  "id": 1,
  "name": "agent #1",
  "url": "http://192.168.50.101:9700",
  "created_at": "2016-02-04t00:18:07.817442z",
  "updated_at": "2016-02-07t01:35:22.223042z"
}

Supported Drivers

See the Reflect Agent documentation for information about supported drivers.

Update a connection

As with adding a new connection, when updating a connection, the relevant connection data is forwarded to the agent and is not stored by the API in any way.

Example request and JSON request body

$ curl -XPUT \
  -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  --data-binary @./connection.json \
  'https://api.reflect.io/v1/agents/1/connections/your-connection-1'

{
  "name": "Your Connection",
  "slug": "your-connection",
  "driver": "postgres",
  "options": {
    "host": "your.host.com",
    "port": "5432",
    "user": "your_user",
    "password": "your_password",
    "database": "your_database",
    "ssl": "require"
  }
}

Example JSON response body

{
  "id": 1,
  "name": "agent #1",
  "url": "http://192.168.50.101:9700",
  "created_at": "2016-02-04t00:18:07.817442z",
  "updated_at": "2016-02-07t01:35:22.223042z"
}

Supported Drivers

Please see the section above for information on supported drivers.

Test a connection

Connect to an agent and test the connection to the database. If the connection succeeds, the server will indicate that the test passed with a passed: true value in the response. If the connection failed, it will respond with a passed: false value and an indicator of why it failed to connect.

Example request and JSON response body

$ curl -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/agents/1/connections/your-connection-1/test'

{
  "passed": true,
  "details": {
    "message": "",
    "vendor_error_code": ""
  }
}

Data models

Data models tell Reflect services how to use the data in your databases to provide reports (which your client-side code then uses to create visualizations). Data models map database columns and expressions to fields, which are referenced at reporting time to generate reports.

Another way to think about it: data models are where the rubber meets the road for reporting and visualization. They map the data in your database to a format that Reflect can understand.

For more in-depth documentation, see Data models.

Data model actions available through the API

• Show a data model
• Update a data model
• Show a project’s data model

Example data model object

{
  "slug": "orders",
  "name": "Order Project Example",
  "description": "An example project and data model for a fictitious ecommerce store.",
  "data_sets": [
    {
      "name": "orders",
      "credential": "reflect-connection-1",
      "tables": [
        {
          "table": "orders",
          "columns": {
            "order_date": "time",
            "order_priority": "text",
            "order_quantity": "number",
            "sales": "number",
            "discount": "number",
            "profit": "number",
            "ship_mode": "text",
            "unit_price": "number",
            "shipping_cost": "number",
            "customer_name": "text",
            "city": "text",
            "zip_code": "number",
            "state": "text",
            "region": "text",
            "customer_segment": "text",
            "product_category": "text",
            "product_sub_category": "text",
            "product_name": "text",
            "product_container": "text",
            "product_base_margin": "number"
          }
        }
      ]
    }
  ],
  "fields": {
    "Order Date": {
      "data_set": "orders",
      "table": "orders",
      "columns": ["order_date"]
    },
    "Customer Name": {
      "data_set": "orders",
      "table": "orders",
      "columns": ["customer_name"]
    },
    "Customer Segment": {
      "data_set": "orders",
      "table": "orders",
      "columns": ["customer_segment"]
    },
    "Region": {
      "data_set": "orders",
      "table": "orders",
      "columns": ["region"]
    },
    "Total Sales": {
      "data_set": "orders",
      "table": "orders",
      "columns": ["sales"],
      "expression": "SUM(sales)"
    },
    "Total Items Sold": {
      "data_set": "orders",
      "table": "orders",
      "columns": ["order_quantity"],
      "expression": "SUM(order_quantity)"
    }
  }
}

Data Sets

Data sets tell Reflect what data lives where in your database and how different parts relate to each other. Each data set has a unique name attribute that is referenced by other parts of the data model.

Data sets also get a credential name which tells the Reflect Agent which connection to use to connect to the database.

Tables

Table definitions are how you tell Reflect what columns live in what tables within your database.

Columns

The physical columns that belong to the table. All physical columns have a type associated with them. The type can be any one of the following:

Relationships

Relationships define how different tables are related to each other. Each relationship has one or more condition objects specifying which keys to join on.

Fields

A field in a data model can be one of the following:

• A column in a table
• A calculation
• An SQL expression

Here are the available parameters for a field configuration object:

Show a data model

List the entirety of a data model by its slug.

Example request and JSON response body

$ curl -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/projects/example-project/data-model'

{
  "name": "Example Project",
  "slug": "example-project",
  "description": "An example project and data model.",
  "data_sets": [
    {
      "name": "example_data_set",
      "credential": "connection-1",
      "tables": [
        {
          "table": "table1",
          "primary_key": "id",
          "columns": {
            "column1": "text"
          }
        }
      ]
    }
  ],
  "fields": {
    "Field 1": {
      "data_set": "example_data_set",
      "table": "table1",
      "columns": ["column1"]
    },
    "Field 2": {
      "data_set": "example_data_set",
      "table": "table1",
      "columns": ["column2"]
    }
  },
  "created_at": "2016-02-22T14:31:41.57292-08:00",
  "updated_at": "2016-02-22T14:31:41.57292-08:00"
}

Update a data model

Update an existing data model. This will overwrite the existing data model.

Example request and JSON request body

$ curl XPUT \
  -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  --data-binary @./data_model.json \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/projects/example-project/data-model'

Example JSON response body

The curl example above assumes that you have this JSON stored in a data_model.json file:

{
  "name": "Example Project",
  "slug": "example-project",
  "description": "This is an example data model",
  "data_sets": [
    {
      "name": "example_data_set",
      "credential": "connection-1",
      "tables": [
        {
          "table": "table1",
          "primary_key": "id",
          "columns": {
            "column1": "text"
          }
        }
      ]
    }
  ],
  "fields": {
    "Field 1": {
      "data_set": "example_data_set",
      "table": "table1",
      "columns": ["column1"]
    },
    "Field 2": {
      "data_set": "example_data_set",
      "table": "table1",
      "columns": ["column2"]
    }
  },
  "created_at": "2016-02-20T12:06:22.57292-02:11",
  "updated_at": "2016-02-22T14:31:41.57292-08:01"
}

Views

Each Reflect view can be configured using a view manifest, which is a JSON object that defines the view’s configuration. A view’s manifest contains both general metadata about the view (see the table directly below) as well as configuration for each visualization component in the view. There are currently five types of visualization component available:

• Timeseries
• Donut
• Key performance indicator (KPI)
• Bars
• Datagrid

Through the API you can both configure general metadata about a view (see the table directly below) as well as provide configuration for each visualization component in the view.

View actions available through the API

• List views
• Create a view
• Show a view
• Update a view
• Delete a view

Example view object

{
  "name": "Report view",
  "slug": "report-view",
  "configuration": {
    "components": [
      {
        "slug": "timeseries-component-1",
        "group": [],
        "id": 1,
        "metrics": [],
        "title": "Timeseries",
        "type": "bars",
        "layout": {
          "x": 0,
          "y": 0,
          "w": 12,
          "h": 2
        }
      },
      {
        "slug": "datagrid-component-1",
        "group": [],
        "id": 2,
        "metrics": [],
        "title": "Datagrid",
        "type": "datagrid",
        "layout": {
          "x": 0,
          "y": 2,
          "w": 12,
          "h": 3
        }
      }
    ],
    "options": {
      "default_range": {
        "count": 2,
        "unit": "week"
      },
      "date_ranges": [
        {
          "count": 2,
          "unit": "week"
        },
        {
          "count": 1,
          "unit": "month"
        },
        {
          "count": 2,
          "unit": "month"
        },
        {
          "count": 3,
          "unit": "month"
        }
      ],
      "control_bars": {
        "config": {
          "title": "Report"
        },
        "title": {
          "enabled": true
        },
        "filters": {
          "enabled": true
        }
      },
      "dimensions": {},
      "filter": [],
      "formatters": {},
      "metrics": {},
      "project_slug": "your-project-slug"
    },
    "version": "1.1.0"
  },
  "created_at": "2016-03-10T19:27:35.423353Z",
  "updated_at": "2016-03-20T23:48:21.99793Z"
}

View configuration

There are two values you can provide in the configuration field of a view object:

Component configuration

Each component in a view consists of its own configuration. This configuration describes the displayed data, how that data is presented, as well as the controls the user can manipulate that component with.

Constructing dimension/metric/group objects

Below, you’ll note that most components accept dimensions, metrics, and/or groups. Typically these are strings that represent that field name in your data model. Constructing them as objects, however, offers expanded flexibility.

Specifying aliases

To alias a field named “Days” into “Days since launch”:

{ "name": "Days", "alias": "Days since launch" }

Specifying selection

Setting dimensions/metrics/groups via the View object only specifies which ones are selectable by the user. If you want to explicitly specify which ones are selected on load:

{ "name": "Days", "selected": true }

This is especially useful when configuring datagrids, as well as components with multiple metrics enabled.

Shared options

Each component type has a slightly different list of options that can be set on it. However, there are some options that can, and sometimes need to be set on each component.

Individual component options

Timeseries

Donut

KPI

Bars

Datagrid

View options

View configurations include not only the configuration for each component, but also some options you can set for the view itself. These options exist in the options object.

Control bars

Control bars are rows that consist of control components. Control components power the interactions within your views.

The control_bars object consists of a config object that allows for configuration of individual control bars.

Each control bar is then enabled by appending a key with one of title, datepicker, or filters, and a value of { enabled: true }.

The datepicker control component has some additional configuration described below.

Date filters

When using the datepicker component, users can drill down into their views by date. Users are able to choose a preset date range to filter on.

date_ranges is an array of objects, each representing a range option. Within each object, count is an integer, and unit is a unit of time, such as year, month, week, day, or hour. They are all relative to now, so an object equaling {count: 3, unit: “week”} represents “three weeks ago until now”.

default_range shares the same structure, but defines the range initially used when the view is initially rendered.

When datepicker is enabled, components will have an additional time option that allows you to select which time field should be filtered on through the datepicker.

Default filters

An optional filters array can be defined off of the root configuration object.

Supported Formatters

We support a number of different types of formatters for the values of fields. More info on formatters can be found in our Embedding tutorial.

List views

Lists all of the views associated with a project (identified by slug).

Example request, JSON request body, and JSON response body

$ curl -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/projects/your-project-1/views'

[
  {
    "name": "Your View 1",
    "identifier": "a1b2c3-view-identifier-d4e5f6",
    "slug": "your-view-1",
    "configuration": {
      "some": ["configuration-goes-here"]
    },
    "created_at": "2017-01-10T20:41:48.176742Z",
    "updated_at": "2017-01-10T20:41:26.711196Z"
  }  
]

Create a view

Creates a new view and associates it with a project (identified by project slug). The slug for the view must be unique; if it is not unique, a 412 Precondition Failed error will be returned by the API, along with details.

Example request and JSON request body

$ curl -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  --data-binary @./view.json \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/projects/your-project-1/views'

The curl example above assumes that you have this JSON stored in a view.json file:

{
  "name": "Your new view",
  "slug": "your-view-1"
}

Example JSON response body

{
  "name": "View Name",
  "identifier": "viewIdentifier",
  "slug": "your-view-1",
  "configuration": {
    "some": ["configuration", "goes", "here"]
  },
  "created_at": "2017-01-10T20:41:48.176742Z",
  "updated_at": "2017-01-10T20:41:26.711196Z"
}

Show a view

Fetches a view, identified by slug, associated with a specific project, also identified by slug. If the view does not exist, a 404 Not Found error will be returned.

Example request

$ curl -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/projects/your-project-1/views/your-view-1'

Example JSON response body

{
  "name": "View Name",
  "identifier": "viewIdentifier",
  "template": "blank",
  "slug": "your-view-1",
  "configuration": {
    "some": ["configuration", "goes", "here"]

  },
  "created_at": "2017-01-10T20:41:48.176742Z",
  "updated_at": "2017-01-10T20:41:26.711196Z"
}

Update a view

Updates an existing view, identified by slug, associated with a specific project, also identified by slug.

Example request and JSON request body

$ curl -XPUT \
  -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  --data-binary @./view.json \
  'https://api.reflect.io/v1/projects/your-project-1/views/your-view-1'

The curl example above assumes that you have this JSON stored in a view.json file:

{
  "configuration": {
    "some": ["configuration", "goes", "here"]
  }
}

Example JSON response body

{
  "name": "View Name",
  "identifier": "viewIdentifier",
  "template": "blank",
  "slug": "your-view-1",
  "configuration": {
    "some": ["configuration", "goes", "here"]
  },
  "created_at": "2017-01-10T20:41:48.176742Z",
  "updated_at": "2017-01-10T20:41:26.711196Z"
}

Delete a view

Deletes a view. If the request is successful, a 201 Created will be returned along with the view that you just deleted in the body.

Example request

$ curl -XDELETE \
  -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/projects/your-project-1/views/your-view-1'

Example JSON response body

We support a number of different types of formatters. These are configured on a per-field bases in the view options.

Name	Description	Example Input	Example Output
percentage	Multiply the field by 100 and format it as a percentage.	0.10	10%
numeric_percentage	Format the field as a percentage but don’t apply the multiplication.	0.10	0.10%
dollars	Format the field as US dollars.	100.125	$100.13
decimal	Format the field as a number with 2 decimal places.	100.125	100.12
numeric	Format the field as a number with a number with no decimal places.	100.125	100
month	Format a timestamp field as its month in English.	2015-01-01 12:15:00-07:00	January 2015
date	Format a timestamp field as a date.	2015-01-01 12:15:00-07:00	01/01/2015
date_with_hour	Format a timestamp field as a date with its hour.	2015-01-01 12:15:00-07:00	01/01/2015 12:00 PM
date_with_time	Format a timestamp field as a date with its hour and minute.	2015-01-01 12:15:00-07:00	01/01/2015 12:15 PM
lowercase	Format a string field in lowercase.	Darth Vader	darth vader
uppercase	Format a string field in uppercase.	Darth Vader	DARTH VADER
web_content	Within a string field, find all of the URLs and turn them in to links.	Check out http://www.google.com	Check out http://www.google.com
image	Turn the string field in to an image.	http://tiny.cc/7wwqiy

Exports

Reflect’s exporting endpoints allow you to generate a report, then retrieve the output of that report in CSV format.

Fetching a data export from the API is a two-step process. You must:

1. create an export request by making a POST request to the /export endpoint for the project; and then
2. use the identifier of that export to GET the export.

These steps are laid out in detail in the sections below.

Exporting actions available through the API

• Create an export request
• Fetch an export by identifier

Create an export request

This step accepts and saves your report settings (outlined below), and on success will return a 201 Created along with a unique identifier for your export.

The following JSON fields may be supplied in the POST body:

The following fields will be included in the response:

Example request and JSON request body

$ curl -XPOST \
  -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  --data-binary @./export.json \
  'https://api.reflect.io/v1/:project-slug/export'

The curl example above assumes that you have this JSON stored in a export.json file:

{
  "dimensions": ["Name"],
  "metrics": ["Places lived"]
}

Example JSON response body

{
  "identifier": "1234-abcd-efghi-jklmn",
  "settings": {
    "dimensions": ["Name"],
    "metrics": ["Places lived"]
  },
  "created_at": "2016-03-10T19:27:35.423353Z",
  "updated_at": "2016-03-10T19:27:35.423353Z"
}

Fetch an export by identifier

Using the identifier given to you in the response of the previous request, this endpoint will return a CSV of your data with Content-Type: text/csv.

Example request

$ curl -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/export/:export-identifier'

A 200 OK will be returned on success. This endpoint accepts no other parameters.

Team members

Reflect offers a team members feature, available through the REST API, that enables you to delegate access to your account to other people that you work with. Both the owner of the account and non-owners invited to share the account may issue calls to this endpoint, including adding and removing other team members. The owner of the account, however, cannot be removed or changed.

Team member actions available through the API

• List team members
• Invite a team member
• Remove a team member

Example team member object

{
  "id": 1,
  "email": "george@a-team.com",
  "name": "George Peppard",
  "company": "The A Team",
  "is_owner": true,
  "is_confirmed": true,
  "created_at": "2016-03-10T19:27:35.423353Z"
}

List team members

Lists all of the team members associated with your account.

Example request and JSON request body

$ curl -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/team-members'

Example JSON response body

[
  {
    "id": 1,
    "email": "george@a-team.com",
    "name": "George Peppard",
    "company": "The A Team",
    "is_owner": true,
    "is_confirmed": true,
    "created_at": "2016-03-10T19:27:35.423353Z"
  },
  {
    "id": 2,
    "email": "Dirk Benedict",
    "name": "dirk@a-team.com",
    "company": "The A Team",
    "is_owner": false,
    "is_confirmed": true,
    "created_at": "2016-03-10T19:27:35.423353Z"
  }
]

Invite a team member

Invite a team member to use Reflect. The user will receive an email to confirm their account shortly after the invitation is complete. A 201 Created will be returned if the user can be invited to your account.

If the user cannot be invited to be a team member (e.g. they already have a Reflect account) then an error will be returned.

Example request and JSON request body

$ curl -XPOST \
  -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  --data-binary @./team-member.json \
  'https://api.reflect.io/v1/team-members'

The curl example above assumes that you have this JSON stored in a team-member.json file:

{
  "name": "Mr. T",
  "email": "mr-t@a-team.com"
}

Example JSON response body

{
  "id": 3,
  "email": "mr-t@a-team.com",
  "name": "Mr. T",
  "company": "The A Team",
  "is_owner": false,
  "is_confirmed": false,
  "created_at": "2016-03-10T19:27:35.423353Z"
}

Remove a team member

Removes a team member’s access to your account. The team member’s account will still be functional–they will be able to log in and create their own projects, views, etc., but they’ll lose access to anything you’ve already created.

If the request is successful, a 200 OK will be returned along with an empty body.

Example request

$ curl -XDELETE \
  -u ':a1b2c3d-your-secure-api-token-4e5f6g7' \
  -H 'Content-Type: application/json' \
  'https://api.reflect.io/v1/team-members/3'

Errors

All errors emitted by the Reflect API are wrapped in a JSON object that provides:

1. The error’s corresponding HTTP status (which will always match the HTTP code returned by the call)
2. An error code, which is essentially a brief slug for the error. A complete listing of codes can be found in Error Codes below.
3. An error message containing narrative-style insight into what went wrong.

There are also two sub-classes of error, validation and agent errors, that you may encounter when interacting with our API.

Example error object

{
  "error": {
    "status": 400,
    "code": "invalid_body",
    "message": "Failed to decode body."
  }
}

Error codes

For a listing of Agent-related error messages, see the table below.

Validation Errors

Validation errors are emitted when you attempt to create or modify a resource but supply a malformed JSON object.

If a validation-related error occurs during your request, a standard error object will be returned along with a messages object listing field-specific errors; each validation error included in the messages array will include the field name as the key and a list of field-specific errors as the value.

Example validation error object

{
  "error": {
    "status": 406,
    "code": "invalid_object",
    "message": "There were some problems with your submission."
  },
  "messages": {
    "slug": [
      "You must specify a slug for this data model."
    ]
  }
}

Agent Errors

If an Agent-related error occurs, you will receive a normal error object from the API along with a messages array that includes all of the specific error objects received from the Agent.

Agent error messages

Example agent error object

{
  "error": {
    "status": 502,
    "code": "agent_error",
    "message": "The Reflect Agent returned an error fulfilling this request."
  },
  "messages": [
    {
      "status": 502,
      "code": "report_generation_failed",
      "message": "Report generation failed."
    }
  ]
}