AgentSkillsCN

research-lightdash-api

研究并深入探究Lightdash API端点，以理解请求与响应的架构及行为。

SKILL.md
--- frontmatter
name: research-lightdash-api
description: Research and investigate Lightdash API endpoints to understand request/response schemas and behavior.

Research Lightdash API

Description

This skill is used to thoroughly research and investigate a Lightdash API endpoint. It involves researching official documentation and performing live verification against a running Lightdash instance to confirm the actual JSON schema, including request parameters and response bodies.

Input

The user should provide:

  1. •API Endpoint: (e.g., /api/v1/projects/:projectUuid/spaces)
  2. •HTTP Method: (GET, POST, PUT, DELETE, PATCH)
  3. •Documentation URL: (Optional) Link to the official Lightdash API docs.

Workflow

1. Documentation Research

  • •Search: Use web_search or WebFetch to find the endpoint details in the Lightdash API Docs.
  • •Analysis:
    • •Identify required and optional request parameters (path, query, body).
    • •Note the expected response structure.
    • •Check if it uses the standard API Response Envelope.

2. Live Schema Verification

If you have access to a Lightdash instance and an API key:

  • •

    Environment Setup:

    • •Check for LIGHTDASH_API_KEY and LIGHTDASH_URL (defaults to https://app.lightdash.cloud) in the environment or .env file.
    • •If missing, inform the user: "To perform live verification, please provide LIGHTDASH_API_KEY and LIGHTDASH_URL."
  • •

    Execution:

    • •

      Use curl to fetch the live response. This is the preferred method.

      bash
      # Example for GET request
curl -X GET "${LIGHTDASH_URL}/api/v1/your/endpoint" \
    -H "Authorization: ApiKey ${LIGHTDASH_API_KEY}" \
    -H "Content-Type: application/json"
    • •

      For POST/PUT requests with a body:

      bash
      curl -X POST "${LIGHTDASH_URL}/api/v1/your/endpoint" \
    -H "Authorization: ApiKey ${LIGHTDASH_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"key": "value"}'
    • •

      Alternatively, use the Schema Verification Script if a Go-based execution is preferred:

      bash
      LIGHTDASH_API_KEY=your_key LIGHTDASH_URL=https://app.lightdash.cloud go run .claude/skills/research-lightdash-api/assets/verify_schema.go /api/v1/your/endpoint
  • •

    Discrepancy Analysis:

    • •Compare the live JSON response with the documentation.
    • •Document any undocumented fields, differences in data types, or unexpected behaviors.
    • •For POST/PUT/PATCH requests, verify if the request body schema matches the documentation.

3. Response Analysis

  • •Envelope Check: Verify if the response is wrapped in the standard { "status": "ok", "results": ... } envelope.
  • •Model Mapping: Draft the Go struct definitions (models) based on the verified schema, ensuring proper types (e.g., UUID strings, timestamps, nullable fields).

Reference

Assets