​
Python Flask Implementation

We’ve created a reference implementation in Python using Flask that demonstrates how to use the Nekt Data API. This implementation provides a simple REST API server that you can run locally to query your data through Nekt.

​
Features

  • All data is processed in your own cloud
  • Simple REST API built with Flask
  • Handles authentication with your Nekt API key
  • Supports creating queries by table name or SQL
  • Handles pagination of results
  • Provides health check endpoint

​
Repository

You can find the full source code on GitHub: github.com/nektcom/data-api-server.

​
Setup

  1. Clone the repository:
git clone https://github.com/nektcom/data-api-server.git
cd data-api-server
  1. Install dependencies using uv:
uv sync
  1. Run the server:
uv run main.py
Once running, the server will be available at http://localhost:5001.

​
Using the API

​
Authentication

All requests (except health check) require your Nekt API key in the x-api-key header: 
curl --location 'localhost:5001/api/queries' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--data '{
    "layer": "layer_name",
    "table": "table_name"
}'

​
Creating Queries

You can create queries in two ways:

​
Using Layer and Table Names

curl --location 'localhost:5001/api/queries' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--data '{
    "layer": "layer_name",
    "table": "table_name",
    "limit": 100
}'

​
Using SQL Query

curl --location 'localhost:5001/api/queries' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--data '{
    "sql_query": "SELECT\n\t*\nFROM\n\t\"layer_name\".\"table_name\""
}'

​
Getting Results

Once you have a query slug (e.g.: explorer-query-8OSP) from the query creation endpoint, you can fetch results: 
curl --location 'localhost:5001/api/queries/explorer-query-8OSP/results?page_number=1' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY'
Results are paginated with 100 records per page: 
{
    "query_slug": "explorer-query-8OSP",
    "page": 1,
    "data": [
        {
            "id": "2666b548-e028-47bd-b44d-0704f2c3ebb8",
            "created_at": "2025-02-07T21:26:11.523",
            "updated_at": "2025-02-08T10:12:58.622",
            "description": "Description of first item",
            ...
        },
        {
            "id": "2691aa3a-278a-4cad-a152-c678d5cd7693",
            "created_at": "2024-12-23T20:02:32.046",
            "updated_at": "2025-03-06T21:30:57.207",
            "description": "Description of second item",
            ...
        }
    ]
}
Continue fetching subsequent pages by incrementing the page_number parameter until you receive fewer than 100 records or an empty array: 
curl --location 'localhost:5001/api/queries/explorer-query-8OSP/results?page_number=2' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY'

{
  "query_slug": "explorer-query-8OSP",
  "page": 2,
  "data": []
}

​
How It Works

The Flask server acts as a middleware between your application and the Nekt Data API:
  1. It accepts your API requests locally
  2. Forwards them to Nekt’s Data API using your API key
  3. Returns the responses directly to your application
This approach provides several benefits:
  • Simplifies authentication handling
  • Abstracts the complexities of working with the Data API directly
  • Provides a reference for implementing your own clients in other languages

​
Implementation Details

The implementation follows the flow described in the Introduction section. Specifically:
  1. Creating queries via the /api/queries endpoint
  2. Getting results via the /api/queries/{query_slug}/results endpoint
  3. Handling pagination to retrieve all results

​
Next Steps

You can use this implementation as a starting point for your own data API client. Consider:
  • Adding caching for frequent queries
  • Implementing error handling and retries
  • Building additional endpoints for your specific use cases
  • Extending the authentication mechanism
For more details on the Data API endpoints themselves, refer to the relevant sections in this documentation.