Skip to main content

API Overview

The My Dashboard API is a RESTful API built with Express.js and TypeScript, providing endpoints for managing Cypress E2E test results, applications, pull requests, JIRA tickets, and more.

Base URL​

Development: http://localhost:3000 Production: Your deployed Railway URL

API Specification​

The complete API specification is available in OpenAPI 3.1 format:

📄 OpenAPI Spec: server/docs/api-documentation/openapi.yaml

Authentication​

All API endpoints (except /health and /api/auth/validate) require authentication via API key.

Header: x-api-key

curl http://localhost:3000/api/apps \
  -H "x-api-key: your-api-key-here"

See Authentication for detailed information.

API Categories​

1. Health Check​

Monitor service health and status.

  • GET /health - Service health check (no auth required)

2. Authentication​

Validate API keys.

  • POST /api/auth/validate - Validate an API key (no auth required)

3. E2E Test Reports​

Manage Cypress end-to-end test execution reports.

  • GET /api/e2e_run_report - Get E2E test report summary
  • GET /api/e2e_run_report/:summaryId/:appId - Get detailed report for specific app

4. E2E Manual Runs​

Trigger manual E2E test executions.

  • POST /api/e2e_manual_runs - Trigger a manual E2E test run

5. Applications​

Manage applications/projects being monitored.

  • GET /api/apps - List all applications
  • GET /api/apps/:id - Get specific application
  • POST /api/apps - Create new application
  • PUT /api/apps/:id - Update application
  • DELETE /api/apps/:id - Delete application

6. Pull Requests​

Track and manage GitHub pull requests.

  • GET /api/pull_requests - List pull requests
  • GET /api/pull_requests/:id - Get specific pull request
  • POST /api/pull_requests - Create pull request record
  • PUT /api/pull_requests/:id - Update pull request
  • DELETE /api/pull_requests/:id - Delete pull request

7. Notifications​

Manage system notifications and alerts.

  • GET /api/notifications - List notifications
  • GET /api/notifications/:id - Get specific notification
  • POST /api/notifications - Create notification
  • PUT /api/notifications/:id - Update notification
  • POST /api/notifications/:id/read - Mark notification as read
  • DELETE /api/notifications/:id - Delete notification

8. JIRA Integration​

Fetch and manage JIRA tickets.

  • GET /api/jira/manual_qa - Get manual QA tickets
  • GET /api/jira/my_tickets - Get tickets assigned to current user

9. To-Do Lists​

Task management functionality.

  • GET /api/to_do_list - List to-do items
  • GET /api/to_do_list/:id - Get specific to-do item
  • POST /api/to_do_list - Create to-do item
  • PUT /api/to_do_list/:id - Update to-do item
  • DELETE /api/to_do_list/:id - Delete to-do item

10. Firebase Cloud Messaging​

Push notification services.

  • POST /api/fcm/register-token - Register device token for push notifications

Request Format​

Headers​

All requests should include:

Content-Type: application/json
x-api-key: your-api-key-here

Request Body​

Request bodies should be valid JSON:

{
  "name": "My Application",
  "code": "my-app"
}

Response Format​

Success Response​

{
  "success": true,
  "data": {
    "id": 1,
    "name": "My Application",
    "code": "my-app"
  }
}

Error Response​

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": [
    {
      "field": "name",
      "message": "Name is required",
      "code": "REQUIRED_FIELD"
    }
  ]
}

HTTP Status Codes​

CodeMeaningDescription
200OKRequest successful
201CreatedResource created successfully
400Bad RequestInvalid request data
401UnauthorizedInvalid or missing API key
403ForbiddenInsufficient permissions
404Not FoundResource not found
409ConflictResource already exists
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer error
503Service UnavailableExternal service error

Error Codes​

CodeDescription
VALIDATION_ERRORRequest validation failed
UNAUTHORIZEDInvalid or missing API key
FORBIDDENInsufficient permissions
NOT_FOUNDResource not found
CONFLICTResource already exists
DATABASE_ERRORDatabase operation failed
EXTERNAL_SERVICE_ERRORExternal service error
INTERNAL_ERRORInternal server error

See Error Handling for detailed error documentation.

Data Formats​

Dates​

All dates are in ISO 8601 format:

2024-01-20T12:00:00.000Z

Booleans​

Boolean values are represented as true or false:

{
  "isCompleted": true,
  "watching": false
}

Numbers​

Numbers are represented without quotes:

{
  "id": 123,
  "successRate": 95.5
}

Pagination​

List endpoints support pagination via query parameters:

GET /api/apps?limit=10&offset=0

Parameters:

  • limit - Number of items per page (default: 50, max: 100)
  • offset - Number of items to skip (default: 0)

Response:

{
  "success": true,
  "data": [...],
  "pagination": {
    "total": 100,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

Filtering and Sorting​

Some endpoints support filtering and sorting:

GET /api/pull_requests?status=open&sort=created_at&order=desc

Check individual endpoint documentation for supported parameters.

Rate Limiting​

The API implements rate limiting to prevent abuse:

  • Authentication endpoints: 3 requests per 15 minutes per IP
  • General endpoints: Configurable per endpoint

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642684800

CORS​

CORS is enabled for all origins in development. In production, configure allowed origins via environment variables.

Versioning​

The API currently does not use versioning. Breaking changes will be communicated in advance.

Using the API​

cURL Example​

# Get all applications
curl http://localhost:3000/api/apps \
  -H "x-api-key: your-api-key-here"

# Create a new application
curl -X POST http://localhost:3000/api/apps \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "name": "My App",
    "code": "my-app",
    "watching": true
  }'

JavaScript/TypeScript Example​

const response = await fetch('http://localhost:3000/api/apps', {
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your-api-key-here'
  }
});

const data = await response.json();
console.log(data);

Using the SDK​

The recommended way to interact with the API is using the TypeScript SDK:

import { MyDashboardAPI } from '@my-dashboard/sdk';

const api = new MyDashboardAPI({
  baseUrl: 'http://localhost:3000',
  apiKey: process.env.API_KEY!
});

// Get all applications
const apps = await api.getApplications();

// Create a new application
const newApp = await api.createApplication({
  name: 'My App',
  code: 'my-app',
  watching: true
});

See SDK Documentation for more information.

API Endpoints Documentation​

Detailed documentation for each endpoint category:

Next Steps​