Reporting API Reference

Overview

The Reporting API provides a comprehensive set of tools for generating, retrieving, and managing reports. You can access pre-defined reports, create custom reports, and schedule report generation.

Endpoints

All API requests should be made to the base URL: https://api.msdn.example.com/v1/reporting

HTTP Method Path Description
GET /reports Retrieves a list of available reports.
GET /reports/{reportId} Retrieves details for a specific report.
POST /reports Creates a new custom report.
PUT /reports/{reportId} Updates an existing custom report.
DELETE /reports/{reportId} Deletes a custom report.
POST /generate/{reportId} Initiates the generation of a report.
GET /generate/status/{jobId} Checks the status of a report generation job.
GET /generate/download/{jobId} Downloads a completed report.
POST /schedule Schedules a report for future generation.
GET /schedule Retrieves a list of scheduled reports.

Report Generation

Initiating Report Generation

To generate a report, use the POST /generate/{reportId} endpoint. You can provide additional parameters in the request body to customize the report.

POST https://api.msdn.example.com/v1/reporting/generate/sales-summary

Request Body Example (for sales-summary report):

{
  "parameters": {
    "startDate": "2023-01-01",
    "endDate": "2023-12-31",
    "region": "North America",
    "format": "pdf"
  }
}

Response:

A successful request will return a JSON object containing a jobId to track the generation process.

{
  "jobId": "abc123xyz789",
  "message": "Report generation initiated successfully."
}

Checking Generation Status

Use the GET /generate/status/{jobId} endpoint to monitor the progress of your report generation job.

GET https://api.msdn.example.com/v1/reporting/generate/status/abc123xyz789

Response:

{
  "jobId": "abc123xyz789",
  "status": "completed", // or "in_progress", "failed"
  "progress": 100,       // Percentage complete
  "reportUrl": "/reports/download/abc123xyz789" // If completed
}

Downloading Reports

Once a report is completed, you can download it using the GET /generate/download/{jobId} endpoint. The response will be the report file itself (e.g., PDF, CSV).

GET https://api.msdn.example.com/v1/reporting/generate/download/abc123xyz789

Scheduling Reports

The Reporting API allows you to schedule reports for automatic generation. Use the POST /schedule endpoint to set up a new schedule.

Request Body Example:

{
  "reportId": "monthly-revenue",
  "schedule": {
    "frequency": "monthly",
    "dayOfMonth": 1,
    "timeOfDay": "08:00:00"
  },
  "parameters": {
    "format": "csv"
  },
  "notificationEmail": "reports@example.com"
}

Response:

{
  "scheduleId": "scl_def456uvw012",
  "message": "Report scheduled successfully."
}

You can retrieve your scheduled reports using GET /schedule.

Custom Report Creation

To create a custom report, use the POST /reports endpoint. You'll need to define the data source, fields, filters, and aggregation logic.

Request Body Example:

{
  "name": "Custom User Activity Report",
  "description": "Tracks user logins and actions over a specified period.",
  "dataSource": "user_activity_logs",
  "fields": ["userId", "timestamp", "action", "details"],
  "filters": {
    "timestamp": {
      "operator": ">=",
      "value": "$startDate"
    }
  },
  "groupBy": ["userId"],
  "aggregation": {
    "actionCount": {"function": "count", "field": "action"}
  },
  "parameters": [
    {"name": "startDate", "type": "date", "required": true, "defaultValue": "2023-01-01"}
  ]
}