Core APIs

The Core APIs provide fundamental functionality for the Stratpoint Timesheet Application, including user management, dashboard operations, and basic data access. These APIs are designed for specific business operations and require userId parameters for most endpoints.

Authentication Headers

All Core API endpoints require authentication:

Authorization: Bearer {jwt_token}
galingsa: timesheetweb
Content-Type: application/json

Dashboard APIs

Dashboard by User ID

Retrieves dashboard data for a specific user.

GET /api/v2/dashboard/byUserId/{userId}

Parameters: - userId: User ID (required)

Permission Required: Permission ID 57

Response:

{
  "header": {
    "status": 200,
    "title": "Dashboard",
    "description": "Data Successfully Retrieved"
  },
  "body": {
    "data": {
      "panels": {
        "timelogs": true,
        "asProjectManager": false,
        "forResourceManager": false,
        "timelogsOutOfEmploymentDuration": false,
        "consumableOffsets": true,
        "leaves": true,
        "asApprover": false,
        "nearingRegularization": false,
        "forFinance": false,
        "forAdmin": false,
        "forCollectionNotice": false
      }
    }
  }
}

Dashboard Timelogs

Retrieves timelog panel data for a specific user.

GET /api/v2/dashboard/timelogs/{userId}

Parameters: - userId: User ID (required)

Response:

{
  "header": {
    "status": 200,
    "title": "Dashboard",
    "description": "Data Successfully Retrieved"
  },
  "body": {
    "data": {
      "recentTimelogs": [
        {
          "id": 12345,
          "day": "2024-01-15",
          "spentHours": "8.00",
          "description": "Development work on authentication module",
          "status": "Approved",
          "projectName": "Client Portal Development"
        }
      ],
      "weeklyHours": "40.00",
      "monthlyHours": "160.00"
    }
  }
}

Dashboard as Project Manager

Retrieves project manager dashboard data.

GET /api/v2/dashboard/asProjectManager/{userId}

Permission Required: Permission to view as project manager

Dashboard for Resource Manager

Retrieves resource manager dashboard data.

GET /api/v2/dashboard/forResourceManager/{userId}

Dashboard Consumable Offsets

Retrieves CTO (Compensatory Time Off) data for a user.

GET /api/v2/dashboard/consumableOffsets/{userId}

Response:

{
  "header": {
    "status": 200,
    "title": "Dashboard",
    "description": "Data Successfully Retrieved"
  },
  "body": {
    "data": {
      "availableOffsets": [
        {
          "id": 456,
          "sourceTimelogId": 12345,
          "hours": "4.00",
          "earnedDate": "2024-01-10",
          "expiryDate": "2024-07-10",
          "isUsed": 0
        }
      ],
      "totalAvailableHours": "16.00"
    }
  }
}

Dashboard Leaves

Retrieves leave-related dashboard data.

GET /api/v2/dashboard/leaves/{userId}

Dashboard as Approver

Retrieves approver dashboard data.

GET /api/v2/dashboard/asApprover/{userId}

Dashboard for Finance

Retrieves finance-related dashboard data.

GET /api/v2/dashboard/forFinance/{userId}

Dashboard for Admin

Retrieves admin dashboard data.

GET /api/v2/dashboard/forAdmin/{userId}

Mark Dashboard Items as Done

Marks dashboard notification items as completed.

POST /api/v2/dashboard/markasdone/{userId}

Request Body:

{
  "itemId": "notification_item_id",
  "itemType": "timelog_reminder"
}

User Management APIs

Get User Profile

Retrieves the current authenticated user's profile information.

GET /api/v2/users/getProfile

Permission Required: Permission ID 160

Response:

{
  "header": {
    "status": 200,
    "title": "Users",
    "description": "Data Successfully Retrieved"
  },
  "body": {
    "data": {
      "id": 123,
      "firstname": "John",
      "lastname": "Doe",
      "email": "john.doe@stratpoint.com",
      "designation": "Senior Developer",
      "department": "Technology",
      "businessUnit": "Digital Solutions",
      "startDate": "2023-01-15",
      "isActive": 1,
      "permission_ids": "1,2,3,57,72",
      "currentHourlyCost": "25.00",
      "skills": [
        "PHP", "JavaScript", "React", "MySQL"
      ],
      "employments": [
        {
          "startDate": "2023-01-15",
          "endDate": null,
          "employmentType": "Regular",
          "designation": "Senior Developer"
        }
      ]
    }
  }
}

Get Project Utilization Report Filters

Retrieves filter options for project utilization reports.

GET /api/v2/users/project-utilization-report-filters

Response:

{
  "header": {
    "status": 200,
    "title": "Users",
    "description": "Data Successfully Retrieved"
  },
  "body": {
    "data": {
      "users": [
        {
          "id": 123,
          "name": "Doe, John M.",
          "isActive": 1
        }
      ],
      "projects": [
        {
          "id": 456,
          "name": "Client Portal Development",
          "isActive": 1
        }
      ],
      "businessUnits": [
        {
          "id": 1,
          "name": "Digital Solutions"
        }
      ]
    }
  }
}

Get Utilization Report by Week

Retrieves weekly utilization report for a specific user.

GET /api/v2/users/getUtilizationReportByWeek/{userId}/{yearMonth}/{reportTypes}/{cadetInclusion?}

Parameters: - userId: User ID (required) - yearMonth: Year and month in YYYY-MM format (required) - reportTypes: Report type filter (required) - cadetInclusion: Include cadet data (optional)

Example:

GET /api/v2/users/getUtilizationReportByWeek/123/2024-01/all/1

Response:

{
  "header": {
    "status": 200,
    "title": "Users",
    "description": "Data Successfully Retrieved"
  },
  "body": {
    "data": {
      "weeklyData": [
        {
          "week": "2024-01-01",
          "totalHours": 40.0,
          "targetHours": 40.0,
          "utilization": 100.0,
          "projectBreakdown": [
            {
              "projectId": 456,
              "projectName": "Client Portal Development",
              "hours": 32.0
            }
          ]
        }
      ]
    }
  }
}

Activate User Access

Activates or deactivates user access.

GET /api/v2/users/activateUserAccess/{userId}/{newValue}

Parameters: - userId: User ID (required) - newValue: 1 for active, 0 for inactive (required)

Career Mentors and Mentees

Retrieves career mentorship relationships.

GET /api/v2/users/career_mentors_mentees

Response:

{
  "header": {
    "status": 200,
    "title": "Users",
    "description": "Data Successfully Retrieved"
  },
  "body": {
    "data": {
      "mentors": [
        {
          "id": 999,
          "name": "Smith, Jane A.",
          "mentees": [
            {
              "id": 123,
              "name": "Doe, John M."
            }
          ]
        }
      ]
    }
  }
}

Data Lookup APIs

Get Filter Data

Most endpoints that return lists also provide getFilters methods for dropdown data.

Example Pattern:

GET /api/v2/{resource}/getFilters

Common Filter Endpoints: - /api/v2/users/getFilters - /api/v2/projects/getFilters - /api/v2/tasktypes/getFilters - /api/v2/subtasktypes/getFilters

Response Format:

{
  "header": {
    "status": 200,
    "title": "Resource Name",
    "description": "Data Successfully Retrieved"
  },
  "body": {
    "data": [
      {
        "id": 1,
        "title": "Display Name",
        "isActive": 1
      }
    ]
  }
}

Standard Resource Operations

CRUD Pattern

Most resources follow this pattern:

GET /api/v2/{resource}

POST /api/v2/{resource}

GET /api/v2/{resource}/{id}

PUT /api/v2/{resource}/{id}

DELETE /api/v2/{resource}/{id}

Available Resources: - users - projects - timelogs - timelog_comments - leaves - tasktypes - subtasktypes - clients - businessunits - currencies - designations - capabilities

Common Response Structure

All API responses follow this structure:

{
  "header": {
    "status": 200,
    "title": "Resource Name",
    "description": "Operation description"
  },
  "body": {
    "data": "actual_data_or_array"
  }
}

Error Response:

{
  "header": {
    "status": 412,
    "title": "Resource Name",
    "description": "Validation error encountered"
  },
  "body": {
    "errors": {
      "field_name": ["Error message"]
    }
  }
}

Access Control

Permission System

Most endpoints check permissions using permission IDs:

• Permission 57: Basic timelog access
• Permission 26: Can view all users
• Permission 72: Can approve timelogs
• Permission 160: Can view user profile
• Permission 61: Can update hourly costs

Access Denied Response

{
  "header": {
    "status": 401,
    "title": "Resource Name",
    "description": "Access not allowed"
  },
  "body": []
}

Key Implementation Notes

1. User-Centric Design: Most endpoints require explicit userId parameters
2. Permission-Based Access: Operations controlled by numeric permission IDs
3. Business Logic Integration: APIs include business rules and validations
4. Header/Body Structure: Consistent response format across all endpoints
5. Resource-Specific Routes: Many endpoints are functional rather than RESTful
6. Integration-Specific: Some endpoints designed for specific integrations (F1, SINOP)

This Core API structure prioritizes business functionality and user-specific data access over generic REST patterns.