Endpoints allow you to create custom API interfaces for your datasets with secure, controlled access. You can define endpoints using YAML configuration that includes filters, queries, and authentication.

Endpoint YAML Configuration

endpoints:
  - name: consolidated-sales-endpoint
    filters:
      - name: country
        type: string
      - name: city
        type: string
    query: |
        SELECT *
        FROM consolidated_sales_df_299ceb
        WHERE 1 = 1
        {% if country is defined %}
        AND CustomerCountry = '{{ country }}'
        {% endif %}
        {% if city is defined %}
        AND CustomerCity = '{{ city }}'
        {% endif %}

Endpoint Configuration Reference

AttributeTypeDescription
namestringUnique endpoint identifier
filtersarrayList of filter parameters
querystringSQL query with Jinja templating support

Filter Types

TypeDescriptionExample
stringText parametercountry, category
integerNumeric parameteryear, limit
floatDecimal parameterprice, rating
dateDate parameterstart_date, end_date
booleanBoolean parameteractive, is_featured

Using Endpoints

Once configured, endpoints are accessible via HTTP GET requests with query parameters:

curl -X GET \
  "https://app.datazone.co/api/v1/endpoint/consolidated-sales-endpoint-391c2587?country=USA&city=New%20York" \
  -H "x-api-key: <DATAZONE_API_KEY>" \
  -H "Content-Type: application/json"

Response Format

Endpoints return JSON data with the following structure:

{
  "records": [
    {
      "column1": "value1",
      "column2": "value2"
    }
  ],
  "metadata": {
    "total_records": 100,
    "query_time_ms": 250,
    "endpoint_name": "consolidated-sales-endpoint"
  }
}

Authentication

Endpoints use API key authentication via the x-api-key header:

-H "x-api-key: YOUR_API_KEY"

Error Responses

Status CodeDescription
200Success
400Bad Request - Invalid parameters
401Unauthorized - Invalid API key
403Forbidden - Access denied
404Not Found - Endpoint doesn’t exist
500Internal Server Error

Example error response:

{
  "error": "Invalid parameter 'country': must be a string",
  "code": "INVALID_PARAMETER",
  "status": 400
}

Advanced Query Features

Jinja Templating

Endpoints support Jinja templating for dynamic queries:

query: |
    SELECT *
    FROM sales_data
    WHERE 1 = 1
    {% if start_date is defined %}
    AND order_date >= '{{ start_date }}'
    {% endif %}
    {% if end_date is defined %}
    AND order_date <= '{{ end_date }}'
    {% endif %}
    {% if categories is defined %}
    AND category IN ({{ categories | join("','") | surround("'") }})
    {% endif %}

Multiple Endpoints

You can define multiple endpoints in a single YAML file:

endpoints:
  - name: sales-summary
    filters:
      - name: year
        type: integer
    query: |
        SELECT 
          SUM(amount) as total_sales,
          COUNT(*) as order_count
        FROM sales_data
        {% if year is defined %}
        WHERE YEAR(order_date) = {{ year }}
        {% endif %}

  - name: product-details
    filters:
      - name: product_id
        type: string
    query: |
        SELECT *
        FROM products
        WHERE product_id = '{{ product_id }}'

Caching

Endpoint responses can be cached:

  • Default cache TTL: 60 minutes
  • Cache headers indicate freshness
  • Use cache-busting parameters when needed