Add REST endpoint for headless Google Analytics queries

[fmontes]

Overview

Adds a REST endpoint at /api/v1/googleanalytics/query for querying Google Analytics 4 data programmatically, enabling headless/API-first use cases beyond Velocity templates.

What Changed

New REST Endpoint

Endpoint: POST /api/v1/googleanalytics/query

Request:

{
  "propertyId": "123456789",
  "startDate": "2026-02-09",
  "endDate": "2026-02-16",
  "metrics": ["sessions", "activeUsers"],
  "dimensions": ["date", "pagePath"],
  "filters": {
    "dimension": [
      {"field": "pagePath", "value": "/products", "operator": "CONTAINS"}
    ]
  },
  "sort": "sessions",
  "maxResults": 100
}

Response (Flattened):

{
  "rowCount": 7,
  "dimensions": ["date", "pagePath"],
  "metrics": ["sessions", "activeUsers"],
  "rows": [
    {
      "date": "20260209",
      "pagePath": "/products",
      "sessions": "150",
      "activeUsers": "120"
    },
    {
      "date": "20260210",
      "pagePath": "/home",
      "sessions": "200",
      "activeUsers": "180"
    }
  ],
  "metadata": {
    "currencyCode": "USD",
    "timeZone": "America/New_York"
  }
}

Response Format

The endpoint returns a flattened, self-documenting response where:

• dimensions array lists dimension field names
• metrics array lists metric field names
• Each row is a named object with field names matching requested dimensions/metrics

This eliminates the need for consumers to track positional array indices and provides better developer experience.

Documentation Updates

• Added REST API usage section with curl examples
• Added "Understanding Dimensions and Metrics" explainer
• Clarified difference between dimensions (categorical grouping) and metrics (numerical measurements)

Why This Matters

Current limitation: The $analytics viewtool only works in Velocity templates, blocking:

• SPAs/headless frontends that need analytics data via API
• External integrations and dashboards
• Mobile apps
• Third-party services

This enables:

• React/Vue/Angular apps to fetch GA4 data client-side
• Headless CMS architectures
• Custom analytics dashboards
• API-driven integrations

Testing

Build

./gradlew clean jar
# Successfully builds to build/libs/google-analytics-0.5.0.jar

Manual Test

curl -X POST http://localhost:8080/api/v1/googleanalytics/query   -H "Content-Type: application/json"   -u admin@dotcms.com:admin   -d '{
    "propertyId": "YOUR_PROPERTY_ID",
    "startDate": "2026-02-09",
    "endDate": "2026-02-16",
    "metrics": ["sessions", "activeUsers"],
    "dimensions": ["date"]
  }'

Expected: JSON response with flattened row structure and named fields.

Breaking Changes

Yes - The response format is a breaking change from positional arrays to named objects.

Acceptable because: This endpoint is being added in this PR and has not yet been released, so no existing consumers are affected.

Files Changed

• src/main/java/com/dotcms/google/analytics/rest/GoogleAnalyticsResource.java - New REST resource with flattened response conversion
• README.md - Added REST API documentation and dimensions/metrics explainer

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This pull request adds a REST API endpoint for querying Google Analytics 4 data, enabling headless and API-first use cases beyond the existing Velocity template-based approach. The endpoint provides a self-documenting JSON response format with named fields rather than positional arrays.

Changes:

• New POST endpoint at /api/v1/googleanalytics/query for programmatic GA4 data queries with flattened response format
• Added JAX-RS dependency and OSGi bundle service registration
• Documentation updates with REST API usage examples and dimensions/metrics explainer

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 14 comments.

File	Description
src/main/java/com/dotcms/google/analytics/rest/GoogleAnalyticsResource.java	New REST resource implementing the /query endpoint with authentication, request validation, and response transformation
src/main/java/com/dotcms/google/analytics/osgi/Activator.java	Added REST resource registration via publishBundleServices call
build.gradle	Added javax.ws.rs-api dependency and bumped version to 0.5.0
README.md	Added REST API usage documentation with curl examples and dimensions/metrics educational content

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated 9 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.