API Documentation

# Complete OpenAPI specification example
openapi: 3.0.3
info:
  title: Data Analytics API
  description: |
    The Data Analytics API provides access to data processing and analytics services.
    
    ## Authentication
    All API endpoints require authentication using API keys or JWT tokens.
    
    ## Rate Limits
    - Standard tier: 1000 requests per hour
    - Premium tier: 10000 requests per hour
    
    ## Support
    For support, contact api-support@example.com
  version: 2.1.0
  contact:
    name: API Support Team
    email: api-support@example.com
    url: https://docs.example.com/support
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
 
servers:
  - url: https://api.example.com/v2
    description: Production server
  - url: https://staging-api.example.com/v2
    description: Staging server
  - url: https://dev-api.example.com/v2
    description: Development server
 
security:
  - ApiKeyAuth: []
  - BearerAuth: []
 
paths:
  /datasets:
    get:
      summary: List datasets
      description: |
        Retrieve a paginated list of available datasets.
        
        You can filter datasets by:
        - Category
        - Creation date range
        - Size range
        
        Results are sorted by creation date (newest first) by default.
      tags:
        - Datasets
      parameters:
        - name: category
          in: query
          description: Filter by dataset category
          required: false
          schema:
            type: string
            enum: [sales, marketing, finance, operations]
          example: sales
        - name: limit
          in: query
          description: Maximum number of results per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: offset
          in: query
          description: Number of results to skip for pagination
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: created_after
          in: query
          description: Filter datasets created after this date
          required: false
          schema:
            type: string
            format: date
          example: "2024-01-01"
      responses:
        '200':
          description: Successfully retrieved datasets
          headers:
            X-Total-Count:
              description: Total number of datasets matching the criteria
              schema:
                type: integer
            X-Rate-Limit-Remaining:
              description: Number of requests remaining in current window
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      ref: '#/components/schemas/Dataset'
                  meta:
                    ref: '#/components/schemas/PaginationMeta'
              examples:
                successful_response:
                  summary: Successful response with datasets
                  value:
                    data:
                      - id: "dataset-123"
                        name: "Sales Q1 2024"
                        category: "sales"
                        size_mb: 1024
                        created_at: "2024-01-15T10:30:00Z"
                    meta:
                      total: 156
                      limit: 20
                      offset: 0
        '400':
          ref: '#/components/responses/BadRequest'
        '401':
          ref: '#/components/responses/Unauthorized'
        '403':
          ref: '#/components/responses/Forbidden'
        '429':
          ref: '#/components/responses/TooManyRequests'
    
    post:
      summary: Create dataset
      description: |
        Upload and create a new dataset in the system.
        
        ### Supported formats:
        - CSV (.csv)
        - JSON (.json)
        - Parquet (.parquet)
        
        ### File size limits:
        - Standard tier: 100MB max
        - Premium tier: 1GB max
      tags:
        - Datasets
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - name
                - category
              properties:
                file:
                  type: string
                  format: binary
                  description: Dataset file to upload
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: Human-readable name for the dataset
                category:
                  type: string
                  enum: [sales, marketing, finance, operations]
                  description: Dataset category
                description:
                  type: string
                  maxLength: 500
                  description: Optional description of the dataset
                tags:
                  type: array
                  items:
                    type: string
                  maxItems: 10
                  description: Tags for organizing datasets
            encoding:
              file:
                contentType: text/csv, application/json, application/octet-stream
      responses:
        '201':
          description: Dataset created successfully
          content:
            application/json:
              schema:
                ref: '#/components/schemas/Dataset'
        '400':
          ref: '#/components/responses/BadRequest'
        '413':
          description: File too large
          content:
            application/json:
              schema:
                ref: '#/components/schemas/Error'
 
  /datasets/{datasetId}/analytics:
    post:
      summary: Run analytics on dataset
      description: |
        Execute analytical operations on a specific dataset.
        
        ### Available operations:
        - Statistical summaries
        - Correlation analysis
        - Data profiling
        - Custom queries
      tags:
        - Analytics
      parameters:
        - name: datasetId
          in: path
          required: true
          description: Unique identifier of the dataset
          schema:
            type: string
            pattern: '^[a-zA-Z0-9-]+'
          example: "dataset-123"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              ref: '#/components/schemas/AnalyticsRequest'
            examples:
              statistical_summary:
                summary: Generate statistical summary
                value:
                  operation: "statistical_summary"
                  parameters:
                    columns: ["sales", "profit", "quantity"]
                    include_percentiles: true
              correlation_analysis:
                summary: Perform correlation analysis
                value:
                  operation: "correlation"
                  parameters:
                    method: "pearson"
                    columns: ["sales", "marketing_spend"]
      responses:
        '200':
          description: Analytics completed successfully
          content:
            application/json:
              schema:
                ref: '#/components/schemas/AnalyticsResult'
 
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        API key authentication. Include your API key in the X-API-Key header.
        
        Example: `X-API-Key: sk_live_abc123def456`
    
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWT token authentication. Include your JWT token in the Authorization header.
        
        Example: `Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`
 
  schemas:
    Dataset:
      type: object
      required:
        - id
        - name
        - category
        - size_mb
        - created_at
      properties:
        id:
          type: string
          description: Unique dataset identifier
          example: "dataset-123"
        name:
          type: string
          description: Human-readable dataset name
          example: "Sales Q1 2024"
        category:
          type: string
          enum: [sales, marketing, finance, operations]
          description: Dataset category
        description:
          type: string
          description: Dataset description
          nullable: true
        size_mb:
          type: number
          format: float
          description: Dataset size in megabytes
          example: 1024.5
        row_count:
          type: integer
          description: Number of rows in the dataset
          example: 150000
        column_count:
          type: integer
          description: Number of columns in the dataset
          example: 25
        created_at:
          type: string
          format: date-time
          description: Dataset creation timestamp
          example: "2024-01-15T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
          example: "2024-01-16T14:22:00Z"
        tags:
          type: array
          items:
            type: string
          description: Dataset tags
          example: ["quarterly", "revenue", "regional"]
        status:
          type: string
          enum: [processing, ready, error]
          description: Current dataset status
          example: "ready"
 
    AnalyticsRequest:
      type: object
      required:
        - operation
      properties:
        operation:
          type: string
          enum: [statistical_summary, correlation, data_profile, custom_query]
          description: Type of analytics operation to perform
        parameters:
          type: object
          description: Operation-specific parameters
          additionalProperties: true
        output_format:
          type: string
          enum: [json, csv, parquet]
          default: json
          description: Desired output format
 
    AnalyticsResult:
      type: object
      properties:
        operation:
          type: string
          description: The operation that was performed
        execution_time_ms:
          type: integer
          description: Execution time in milliseconds
        result:
          type: object
          description: Operation results
          additionalProperties: true
        download_url:
          type: string
          format: uri
          description: URL to download detailed results
          nullable: true
 
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
          description: Total number of items
        limit:
          type: integer
          description: Maximum items per page
        offset:
          type: integer
          description: Number of items skipped
        has_more:
          type: boolean
          description: Whether there are more items available
 
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Error code for programmatic handling
              example: "INVALID_REQUEST"
            message:
              type: string
              description: Human-readable error message
              example: "The request is invalid"
            details:
              type: object
              description: Additional error details
              additionalProperties: true
            trace_id:
              type: string
              description: Unique identifier for tracking this error
              example: "req_abc123def456"
 
  responses:
    BadRequest:
      description: Bad Request - Invalid input parameters
      content:
        application/json:
          schema:
            ref: '#/components/schemas/Error'
          examples:
            validation_error:
              summary: Validation error
              value:
                error:
                  code: "VALIDATION_ERROR"
                  message: "Request validation failed"
                  details:
                    field_errors:
                      category: "Value must be one of: sales, marketing, finance, operations"
    
    Unauthorized:
      description: Unauthorized - Authentication required
      content:
        application/json:
          schema:
            ref: '#/components/schemas/Error'
    
    Forbidden:
      description: Forbidden - Insufficient permissions
      content:
        application/json:
          schema:
            ref: '#/components/schemas/Error'
    
    TooManyRequests:
      description: Too Many Requests - Rate limit exceeded
      headers:
        Retry-After:
          description: Seconds to wait before making another request
          schema:
            type: integer
      content:
        application/json:
          schema:
            ref: '#/components/schemas/Error'
 
tags:
  - name: Datasets
    description: Dataset management operations
  - name: Analytics
    description: Data analytics and processing operations

// JavaScript SDK example
class DataAnalyticsClient {
    constructor(apiKey, baseUrl = 'https://api.example.com/v2') {
        this.apiKey = apiKey;
        this.baseUrl = baseUrl;
        this.headers = {
            'X-API-Key': apiKey,
            'Content-Type': 'application/json'
        };
    }
 
    /**
     * List datasets with optional filtering
     * @param {Object} options - Filter options
     * @param {string} options.category - Filter by category
     * @param {number} options.limit - Maximum results (default: 20)
     * @param {number} options.offset - Results offset (default: 0)
     * @returns {Promise<Array>} Array of dataset objects
     * 
     * @example
     * const client = new DataAnalyticsClient('your-api-key');
     * const datasets = await client.listDatasets({
     *     category: 'sales',
     *     limit: 10
     * });
     * console.log(`Found {datasets.length} datasets`);
     */
    async listDatasets({ category, limit = 20, offset = 0 } = {}) {
        const params = new URLSearchParams({
            limit: limit.toString(),
            offset: offset.toString()
        });
        
        if (category) {
            params.append('category', category);
        }
        
        const response = await fetch(`{params}`, {
            headers: this.headers
        });
        
        if (!response.ok) {
            throw new Error(`API error: {response.statusText}`);
        }
        
        const data = await response.json();
        return data.data;
    }
 
    /**
     * Create a new dataset by uploading a file
     * @param {Object} options - Dataset creation options
     * @param {string} options.name - Dataset name
     * @param {string} options.category - Dataset category
     * @param {File|Buffer} options.file - File to upload
     * @param {string} [options.description] - Optional description
     * @returns {Promise<Object>} Created dataset object
     * 
     * @example
     * const client = new DataAnalyticsClient('your-api-key');
     * const fileInput = document.getElementById('file-input');
     * const dataset = await client.createDataset({
     *     name: 'Q1 Sales',
     *     category: 'sales',
     *     file: fileInput.files[0],
     *     description: 'First quarter sales data'
     * });
     * console.log(`Created dataset: {dataset.id}`);
     */
    async createDataset({ name, category, file, description }) {
        const formData = new FormData();
        formData.append('name', name);
        formData.append('category', category);
        formData.append('file', file);
        
        if (description) {
            formData.append('description', description);
        }
        
        const response = await fetch(`{this.baseUrl}/datasets`, {
            method: 'POST',
            headers: {
                'X-API-Key': this.apiKey
                // Don't set Content-Type for FormData
            },
            body: formData
        });
        
        if (!response.ok) {
            const error = await response.json();
            throw new Error(`API error: {error.error.message}`);
        }
        
        return await response.json();
    }
}
 
// Usage example
const client = new DataAnalyticsClient('sk_live_your_api_key_here');
 
// List datasets
try {
    const datasets = await client.listDatasets({ category: 'sales' });
    console.log('Sales datasets:', datasets);
} catch (error) {
    console.error('Error listing datasets:', error.message);
}

# List datasets
curl -X GET "https://api.example.com/v2/datasets?category=sales&limit=10" \
  -H "X-API-Key: sk_live_your_api_key_here" \
  -H "Accept: application/json"
 
# Create dataset
curl -X POST "https://api.example.com/v2/datasets" \
  -H "X-API-Key: sk_live_your_api_key_here" \
  -F "name=Q1 Sales Data" \
  -F "category=sales" \
  -F "description=First quarter sales figures" \
  -F "file=@sales_data.csv"
 
# Run analytics
curl -X POST "https://api.example.com/v2/datasets/dataset-123/analytics" \
  -H "X-API-Key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "statistical_summary",
    "parameters": {
      "columns": ["sales", "profit", "quantity"],
      "include_percentiles": true
    }
  }'

{
  "info": {
    "name": "Data Analytics API",
    "description": "Complete test collection for the Data Analytics API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "apikey",
    "apikey": [
      {
        "key": "key",
        "value": "X-API-Key",
        "type": "string"
      },
      {
        "key": "value",
        "value": "{{api_key}}",
        "type": "string"
      }
    ]
  },
  "variable": [
    {
      "key": "base_url",
      "value": "https://api.example.com/v2"
    },
    {
      "key": "api_key",
      "value": "sk_live_your_api_key_here"
    }
  ],
  "item": [
    {
      "name": "List Datasets",
      "request": {
        "method": "GET",
        "url": {
          "raw": "{{base_url}}/datasets?category=sales&limit=10",
          "host": ["{{base_url}}"],
          "path": ["datasets"],
          "query": [
            {"key": "category", "value": "sales"},
            {"key": "limit", "value": "10"}
          ]
        }
      },
      "event": [
        {
          "listen": "test",
          "script": {
            "exec": [
              "pm.test('Status code is 200', function () {",
              "    pm.response.to.have.status(200);",
              "});",
              "",
              "pm.test('Response has data array', function () {",
              "    const jsonData = pm.response.json();",
              "    pm.expect(jsonData).to.have.property('data');",
              "    pm.expect(jsonData.data).to.be.an('array');",
              "});"
            ]
          }
        }
      ]
    }
  ]
}