Skip to main content

API YAML

In your Rill project directory, create a new file name <api-name>.yaml in the apis directory containing a custom API definition. See comprehensive documentation on how to define and use custom APIs

Properties​

type​

[string] - Refers to the resource type and must be api (required)

openapi​

[object] - OpenAPI specification for the API endpoint

  • summary - [string] - A brief description of what the API endpoint does

  • parameters - [array of object] - List of parameters that the API endpoint accepts

  • request_schema - [object] - JSON schema for the request body (use nested YAML instead of a JSON string)

  • response_schema - [object] - JSON schema for the response body (use nested YAML instead of a JSON string)

security​

[object] - Defines security rules and access control policies for resources

  • access - [oneOf] - Expression indicating if the user should be granted access to the dashboard. If not defined, it will resolve to false and the dashboard won't be accessible to anyone. Needs to be a valid SQL expression that evaluates to a boolean.

    • option 1 - [string] - SQL expression that evaluates to a boolean to determine access

    • option 2 - [boolean] - Direct boolean value to allow or deny access

  • row_filter - [string] - SQL expression to filter the underlying model by. Can leverage templated user attributes to customize the filter for the requesting user. Needs to be a valid SQL expression that can be injected into a WHERE clause

  • include - [array of object] - List of dimension or measure names to include in the dashboard. If include is defined all other dimensions and measures are excluded

    • if - [string] - Expression to decide if the column should be included or not. It can leverage templated user attributes. Needs to be a valid SQL expression that evaluates to a boolean (required)

    • names - [anyOf] - List of fields to include. Should match the name of one of the dashboard's dimensions or measures (required)

      • option 1 - [array of string] - List of specific field names to include

      • option 2 - [string] - Wildcard '*' to include all fields

  • exclude - [array of object] - List of dimension or measure names to exclude from the dashboard. If exclude is defined all other dimensions and measures are included

    • if - [string] - Expression to decide if the column should be excluded or not. It can leverage templated user attributes. Needs to be a valid SQL expression that evaluates to a boolean (required)

    • names - [anyOf] - List of fields to exclude. Should match the name of one of the dashboard's dimensions or measures (required)

      • option 1 - [array of string] - List of specific field names to exclude

      • option 2 - [string] - Wildcard '*' to exclude all fields

  • rules - [array of object] - List of detailed security rules that can be used to define complex access control policies

    • type - [string] - Type of security rule - access (overall access), field_access (field-level access), or row_filter (row-level filtering) (required)

    • action - [string] - Whether to allow or deny access for this rule

    • if - [string] - Conditional expression that determines when this rule applies. Must be a valid SQL expression that evaluates to a boolean

    • names - [array of string] - List of field names this rule applies to (for field_access type rules)

    • all - [boolean] - When true, applies the rule to all fields (for field_access type rules)

    • sql - [string] - SQL expression for row filtering (for row_filter type rules)

skip_nested_security​

[boolean] - Flag to control security inheritance

One of Properties Options​

SQL Query​

Executes a raw SQL query against the project's data models.

sql​

[string] - Raw SQL query to run against existing models in the project. (required)

connector​

[string] - specifies the connector to use when running SQL or glob queries.

Metrics View Query​

Executes a SQL query that targets a defined metrics view.

metrics_sql​

[string] - SQL query that targets a metrics view in the project (required)

Custom API Call​

Calls a custom API defined in the project to compute data.

api​

[string] - Name of a custom API defined in the project. (required)

args​

[object] - Arguments to pass to the custom API.

File Glob Query​

Uses a file-matching pattern (glob) to query data from a connector.

glob​

[anyOf] - Defines the file path or pattern to query from the specified connector. (required)

  • option 1 - [string] - A simple file path/glob pattern as a string.

  • option 2 - [object] - An object-based configuration for specifying a file path/glob pattern with advanced options.

connector​

[string] - Specifies the connector to use with the glob input.

Resource Status Check​

Uses the status of a resource as data.

resource_status​

[object] - Based on resource status (required)

  • where_error - [boolean] - Indicates whether the condition should trigger when the resource is in an error state.

Examples​

# Example: This api returns the top 10 authors by net line changes since the specified date provided in the arguments.
type: api
name: metrics_view_api
metrics_sql: |-
    SELECT author_name, net_line_changes
    FROM advanced_metrics_view
      where author_date > '{{ .args.date }}'
      order by net_line_changes DESC
      limit 10