endpoint-example
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-example

​
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