vitepress-template

Appearance

REST API Endpoints ​

**Referenced Files in This Document** - [[README.md]](file/bi-intra/apisix/readme.md) - [[services.yaml]](file/bi-intra/apisix/services.yaml) - [[auth_http.pb.go]](file/bi-tenant/api/tenant/v1/auth-http.pb.go) - [[auth.proto]](file/bi-tenant/api/tenant/v1/auth.proto) - [[auth.pb.go]](file/bi-tenant/api/tenant/v1/auth.pb.go) - [[openapi.swagger.json]](file/bi-tenant/docs/openapi/openapi.swagger.json) - [[auth.ts]](file/ui-web/src/api/auth.ts) - [[response.go]](file/bi-common/apitypes/response.go) - [[error.go]](file/bi-common/apitypes/error.go) - [[page.proto]](file/bi-common/api/common/v1/page.proto) - [[cors.go]](file/bi-common/apitypes/middleware/cors.go) - [[metric_http.pb.go]](file/bi-server/api/metric/v1/metric-http.pb.go) - [[metric.proto]](file/bi-server/api/metric/v1/metric.proto)

Table of Contents ​

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction ​

This document provides comprehensive REST API documentation for HTTP clients consuming the BI Analysis Platform. It covers authentication APIs, tenant management endpoints, metric APIs, and data access endpoints exposed through the APISIX gateway. For each endpoint, you will find HTTP methods, URL patterns, request headers, query parameters, request body schemas, and response formats. Authentication mechanisms (JWT tokens), error response codes, standard error schemas, pagination patterns, filtering options, sorting capabilities, practical curl examples, JavaScript fetch implementations, and SDK usage patterns are included. Rate limiting policies, CORS configuration, and API versioning strategies are also addressed.

Project Structure ​

The platform exposes microservices behind the APISIX gateway. Services are discovered via Nacos and routed based on URL prefixes. The tenant service hosts authentication endpoints, while other services (basic, analysis, notify, etc.) expose domain-specific APIs. The gateway enforces security policies, JWT authentication, and path rewriting.

Diagram sources

Section sources

Core Components ​

  • APISIX Gateway: Routes, security, JWT, rate limiting, WAF, and path rewrite.
  • Tenant Service: Authentication and user info endpoints.
  • Basic Service: Domain data endpoints (orders, goods, categories).
  • Analytics Service: Metric definitions and analytics queries.
  • System Service: System administration endpoints.
  • Notification Service: Notification collection endpoints.
  • External Integrations: Leke and Jushuitan APIs.

Section sources

Architecture Overview ​

The APISIX gateway terminates TLS, applies security checks, authenticates JWT, rewrites paths, and forwards requests to backend services discovered via Nacos. Environment routing supports dev/local/test variants using URL prefixes or the X-Env header.

Diagram sources

Section sources

Detailed Component Analysis ​

Authentication APIs (Tenant Service) ​

These endpoints manage login, logout, user info retrieval, menus, token refresh, and favorites.

  • Base URL Pattern: /tenant/api/v1/tenant/...
  • Path Rewriting: APISIX rewrites to /api/v1/tenant/... internally.
  • Authentication: JWT required for protected routes; login and captcha endpoints are whitelisted.

Endpoints:

  • POST /tenant/api/v1/tenant/auth/login

    • Purpose: Authenticate user and return access token.
    • Request headers: Content-Type: application/json
    • Request body:
      • tenant_code: string
      • username: string
      • password: string
      • captcha_id: string
      • captcha_code: string
    • Response:
      • code: number (0 indicates success)
      • message: string
      • data.access_token: string
      • data.token_type: string
      • data.expires_in: number
    • Example curl:

  • POST /tenant/api/v1/tenant/auth/logout

  • GET /tenant/api/v1/tenant/auth/info

  • GET /tenant/api/v1/tenant/auth/menus

  • POST /tenant/api/v1/tenant/auth/refresh

    • Purpose: Refresh access token.
    • Request headers: Content-Type: application/json
    • Request body: refresh_token: string
    • Response: Standard response envelope with new tokens
    • Example curl:

  • GET /tenant/api/v1/tenant/auth/captcha

  • GET /tenant/api/v1/tenant/auth/init

  • POST /tenant/api/v1/tenant/auth/favorite

    • Purpose: Set favorite items.
    • Request headers: Authorization: Bearer <token>, Content-Type: application/json
    • Request body: Favorite data
    • Response: Standard response envelope
    • Example curl:

  • GET /tenant/api/v1/tenant/auth/favorite

Authentication headers injected by APISIX JWT:

  • x-user-id: numeric user identifier
  • x-tenant-id: numeric tenant identifier
  • x-username: string username
  • x-is-admin: boolean admin flag
  • x-role-ids: array of role identifiers

Environment routing:

  • URL prefix mode: /tenant/* (dev), /local/tenant/* (local), /test/tenant/* (test)
  • Header mode: X-Env: local|test (with /tenant/* URL)

Section sources

Tenant Management Endpoints (Tenant Service) ​

The tenant service exposes administrative and user management endpoints under the tenant prefix. APISIX rewrites tenant URLs to internal service paths. Use the same JWT authentication pattern as above.

Common patterns:

  • GET /tenant/api/v1/tenant/users
    • Query parameters: page, limit (via pagination)
    • Response: Standard response envelope with paginated data
  • GET /tenant/api/v1/tenant/orgs
    • Query parameters: status, name
    • Response: Standard response envelope with org data
  • POST /tenant/api/v1/tenant/roles
    • Request body: Role creation payload
    • Response: Standard response envelope with created role
  • PUT /tenant/api/v1/tenant/roles/
    • Path parameters: id
    • Request body: Role update payload
    • Response: Standard response envelope with updated role
  • DELETE /tenant/api/v1/tenant/roles/
    • Path parameters: id
    • Response: Standard response envelope with deletion result

Pagination:

  • Query parameters: page_num (default 1), page_size (default 10, max 100)
  • Response envelope includes data and pagination metadata

Filtering and Sorting:

  • Filtering: query parameters per endpoint (e.g., status, name)
  • Sorting: query parameters per endpoint (e.g., sort=name,desc)

Section sources

Metric APIs (Analytics Service) ​

The analytics service exposes metric definitions and management endpoints.

Endpoints:

  • GET /analysis/api/v1/analytics/metrics

    • Purpose: List available metrics grouped by category.
    • Query parameters: group_filter (optional)
    • Response: Standard response envelope with groups and metrics

  • POST /analysis/api/v1/analytics/metrics

    • Purpose: Create a new metric (derived, order, or formula).
    • Request headers: Authorization: Bearer <token>, Content-Type: application/json
    • Request body: Metric definition (id, name, display_name, description, group, type, and specific config)
    • Response: Standard response envelope with created metric

  • PUT /analysis/api/v1/analytics/metrics/

    • Purpose: Update an existing metric definition.
    • Path parameters: id
    • Request headers: Authorization: Bearer <token>, Content-Type: application/json
    • Request body: Metric update with FieldMask
    • Response: Standard response envelope with updated metric

  • DELETE /analysis/api/v1/analytics/metrics/

    • Purpose: Soft-delete a metric.
    • Path parameters: id
    • Response: Standard response envelope with success flag

Metric data structures:

  • Metric: id, name, display_name, description, group, type, and specific configs (derived, order, formula)
  • DerivedConfig: source_field, aggregation, time_range_field
  • OrderConfig: order_field, time_basis, query_condition
  • FormulaConfig: expression, dependency_ids

Section sources

Data Access Endpoints (Basic Service) ​

The basic service exposes domain data endpoints (orders, goods, categories, shops, etc.). These endpoints follow consistent patterns with pagination, filtering, and sorting.

Examples:

  • GET /basic/api/v1/basic/orders

    • Query parameters: page_num, page_size, filters (per endpoint)
    • Response: Standard response envelope with orders

  • GET /basic/api/v1/basic/goods

    • Query parameters: page_num, page_size, filters (per endpoint)
    • Response: Standard response envelope with goods

  • GET /basic/api/v1/basic/good-category

    • Query parameters: page_num, page_size, filters (per endpoint)
    • Response: Standard response envelope with categories

Filtering and Sorting:

  • Filtering: query parameters per endpoint (e.g., status, date range)
  • Sorting: query parameters per endpoint (e.g., sort=created_at,desc)

Section sources

Notifications Endpoint (Notify Service) ​

The notification service exposes collection endpoints.

Example:

  • POST /notify/api/v1/notify/collect/list
    • Purpose: List collected notifications.
    • Request headers: Authorization: Bearer <token>, Content-Type: application/json
    • Request body: Filters/pagination payload
    • Response: Standard response envelope with collected items

Section sources

External Integrations ​

  • Leke API Service: Exposed under /api-leke/*
  • Jushuitan API Service: Exposed under /api-jushuitan/*

Use the same JWT authentication and environment routing patterns described above.

Section sources

Dependency Analysis ​

The gateway depends on Nacos for service discovery and applies security and authentication plugins. Services depend on shared response/error schemas and pagination models.

Diagram sources

Section sources

Performance Considerations ​

  • Rate Limiting: Enabled by default with configurable rate and burst values keyed by remote address.
  • WAF: Enabled with built-in rules for SQL injection, XSS, path traversal, command injection, sensitive file access, and SSRF.
  • Upstream Timeout and Retries: Configured for balanced reliability and latency.
  • Path Rewriting: Reduces path length and simplifies internal routing.

Recommendations:

  • Tune rate limits per service based on traffic patterns.
  • Monitor WAF blocked requests and adjust rules if needed.
  • Use pagination and efficient filters to reduce payload sizes.

Section sources

Troubleshooting Guide ​

  • Authentication failures:

    • Ensure Authorization: Bearer <token> is present for protected endpoints.
    • Verify JWT_SECRET matches the environment and token was issued by the correct tenant service.
    • Confirm X-Env header or URL prefix matches the environment where the token was generated.

  • Environment routing:

    • If using X-Env header, ensure it is set to local or test as appropriate.
    • Tokens are not cross-environment compatible.

  • Standard error schema:

    • All HTTP responses use a unified envelope with code, message, and optional data.
    • Business error codes are mapped to HTTP status semantics internally; clients should inspect the code field for business errors.

  • Pagination:

    • Use page_num and page_size query parameters; defaults are 1 and 10 respectively, with a maximum page size of 100.

  • CORS:

    • Default CORS allows credentials and common headers; adjust AllowOrigins and AllowCredentials as needed.

Section sources

Conclusion ​

The BI Analysis Platform exposes a well-defined set of REST endpoints through APISIX, with consistent authentication, error handling, and pagination patterns. By leveraging JWT, environment routing, and standardized response envelopes, clients can reliably integrate with tenant management, analytics, basic data, and external integrations.

Appendices ​

Authentication Mechanisms ​

  • JWT Bearer tokens are required for most endpoints.
  • APISIX injects user identity headers extracted from the token.
  • Login and captcha endpoints are whitelisted; environment routing supports dev/local/test.

Section sources

Error Response Schema ​

  • All responses follow a standard envelope:

    • code: number (0 indicates success)
    • message: string
    • data: object or null

  • Business errors carry an additional business code mapped to HTTP semantics internally.

Section sources

Pagination, Filtering, and Sorting ​

  • Pagination:
    • page_num: integer, default 1
    • page_size: integer, default 10, max 100
  • Filtering and sorting:
    • Implemented via query parameters per endpoint; consult service OpenAPI docs for specifics.

Section sources

Practical Examples ​

Section sources

API Versioning Strategies ​

  • Versioning is primarily URL-based (e.g., /api/v1/...).
  • Some services also support Accept headers for version negotiation.

Section sources

CORS Configuration ​

  • Default configuration allows credentials and common headers.
  • Customize AllowOrigins, AllowCredentials, and MaxAge as needed.

Section sources