Skip to content

API Structure

The Stratpoint Timesheet Application provides a comprehensive RESTful API architecture designed to support web applications, mobile clients, and third-party integrations. This section details the API structure, conventions, and implementation patterns.

API Architecture Overview

API Versioning Strategy

graph TB
    A[Client Request] --> B[Route Resolution]
    B --> C[Middleware Stack]
    C --> D[Controller Layer]
    D --> E[Service Layer]
    E --> F[Data Layer]

Current Implementation: - v2: Primary API version (only active version) - Single Version: All routes use /api/v2/ prefix - No Legacy Support: No v1 or v3 versions exist in current implementation

Base URL Structure

https://timesheet.stratpoint.com/api/{version}/{resource}

Examples: - https://timesheet.stratpoint.com/api/v2/timelogs - https://timesheet.stratpoint.com/api/v2/projects - https://timesheet.stratpoint.com/api/v2/users

RESTful Resource Design

Actual API Patterns

Laravel Resource Routes: 

Route::resource('timelogs', 'TimelogController', ['except' => ['create', 'edit']]);
Route::resource('projects', 'ProjectController', ['except' => ['create', 'edit']]);
Route::resource('users', 'UserController', ['except' => ['create', 'edit']]);

Action-Based Routes (Common Pattern): 

POST   /api/v2/timelogs/{userId}/{startDate}/{endDate}    # Get timelogs with filters
GET    /api/v2/timelogs/userWeeklyReport/{userId}         # Weekly report
POST   /api/v2/timelogs/changeStatus                      # Change timelog status
POST   /api/v2/timelogs/userDetailedTaskReport            # Detailed reports

Dashboard-Specific Routes: 

GET    /api/v2/dashboard/byUserId/{userId}               # User dashboard
GET    /api/v2/dashboard/asProjectManager/{userId}       # PM dashboard
GET    /api/v2/dashboard/asApprover/{userId}             # Approver dashboard

Resource Naming Conventions

Plural Nouns for Collections: - /timelogs (not /timelog) - /projects (not /project) - /users (not /user)

Kebab-case for Multi-word Resources: - /payment-milestones - /project-users - /leave-adjustments

Nested Resources for Relationships: - /projects/{id}/users - /users/{id}/timelogs - /projects/{id}/payment-milestones

Core API Resources

Timesheet Management APIs

Actual Timelog Routes: 

# Laravel Resource Routes (GET, POST, PUT, DELETE)
Route::resource('timelogs', 'TimelogController', ['except' => ['create', 'edit']]);

# Custom Action Routes
POST   /api/v2/timelogs/{userId}/{startDate}/{endDate}           # Get timelogs with date range
POST   /api/v2/timelogs/getTaskCalendarData/{userId}/{startDate}/{endDate}  # Calendar data
GET    /api/v2/timelogs/getTotalLoggedHoursPerDay/{userId}/{startDate}/{endDate}  # Daily totals
GET    /api/v2/timelogs/userWeeklyReport/{userId}                # Weekly reports
GET    /api/v2/timelogs/teamDailyReport/{projectId}              # Team reports
POST   /api/v2/timelogs/changeStatus                             # Status changes
POST   /api/v2/timelogs/userDetailedTaskReport                   # Detailed reports
POST   /api/v2/timelogs/approverDetailedTaskReport               # Approver reports
GET    /api/v2/timelogs/offsets/available/{userId}               # Available offsets

Query Parameters for Timelogs: 

?user_id=123                          # Filter by user
?project_id=456                       # Filter by project
?start_date=2024-01-01                # Date range start
?end_date=2024-01-31                  # Date range end
?status=pending                       # Filter by status
?page=1&per_page=50                   # Pagination
?sort=created_at&order=desc           # Sorting

Project Management APIs

Projects Resource: 

GET    /api/v2/projects                # List projects
POST   /api/v2/projects                # Create project
GET    /api/v2/projects/{id}           # Get project details
PUT    /api/v2/projects/{id}           # Update project
DELETE /api/v2/projects/{id}           # Delete project

# Project relationships
GET    /api/v2/projects/{id}/users     # Project team members
POST   /api/v2/projects/{id}/users     # Assign user to project
DELETE /api/v2/projects/{id}/users/{user_id} # Remove user from project

# Project analytics
GET    /api/v2/projects/{id}/analytics # Project analytics
GET    /api/v2/projects/{id}/revenue   # Revenue tracking
GET    /api/v2/projects/{id}/utilization # Utilization metrics

User Management APIs

Users Resource: 

GET    /api/v2/users                   # List users
POST   /api/v2/users                   # Create user
GET    /api/v2/users/{id}              # Get user details
PUT    /api/v2/users/{id}              # Update user
DELETE /api/v2/users/{id}              # Deactivate user

# User relationships
GET    /api/v2/users/{id}/projects     # User's projects
GET    /api/v2/users/{id}/timelogs     # User's timelogs
GET    /api/v2/users/{id}/leaves       # User's leaves

# User utilities
GET    /api/v2/users/profile           # Current user profile
PUT    /api/v2/users/profile           # Update profile
GET    /api/v2/users/permissions       # User permissions

Response Format Standards

Standard Response Structure

Actual Success Response Structure: 

{
  "header": {
    "status": 200,
    "title": "Resource Name",
    "description": "Operation completed successfully"
  },
  "body": {
    "data": [...]
  }
}

Simple Data Response (Common): 

{
  "data": [...],
  "pagination": {
    "current_page": 1,
    "last_page": 10,
    "per_page": 50,
    "total": 500
  }
}

Actual Error Response Structure: 

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

Laravel Validation Errors (Standard): 

{
  "message": "The given data was invalid.",
  "errors": {
    "startTime": ["The start time field is required."],
    "description": ["The description must be at least 10 characters."]
  }
}

HTTP Status Codes

Success Codes: - 200 OK: Successful GET, PUT, PATCH - 201 Created: Successful POST - 204 No Content: Successful DELETE

Client Error Codes: - 400 Bad Request: Invalid request format - 401 Unauthorized: Authentication required - 403 Forbidden: Insufficient permissions - 404 Not Found: Resource not found - 422 Unprocessable Entity: Validation errors - 429 Too Many Requests: Rate limit exceeded

Server Error Codes: - 500 Internal Server Error: Server error - 502 Bad Gateway: Upstream server error - 503 Service Unavailable: Service temporarily unavailable

Request/Response Examples

Creating a Timelog

Request: 

POST /api/v2/timelogs HTTP/1.1
Host: timesheet.stratpoint.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Content-Type: application/json

{
  "startTime": "2024-01-15T09:00:00Z",
  "stopTime": "2024-01-15T17:00:00Z",
  "project_user_id": 123,
  "tasktype_id": 1,
  "description": "Implemented user authentication module",
  "location": "office",
  "tags": ["development", "authentication"]
}

Response: 

HTTP/1.1 201 Created
Content-Type: application/json

{
  "header": {
    "status": 201,
    "title": "Timelog Created",
    "description": "Timelog entry created successfully"
  },
  "body": {
    "data": {
      "id": 1001,
      "user_id": 456,
      "project_user_id": 123,
      "tasktype_id": 1,
      "startTime": "2024-01-15T09:00:00Z",
      "stopTime": "2024-01-15T17:00:00Z",
      "spentHours": 8.0,
      "description": "Implemented user authentication module",
      "status": "pending",
      "location": "office",
      "tags": ["development", "authentication"],
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  }
}

Querying Timelogs with Filters

Request: 

GET /api/v2/timelogs?start_date=2024-01-01&end_date=2024-01-31&status=approved&page=1&per_page=25 HTTP/1.1
Host: timesheet.stratpoint.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Response: 

HTTP/1.1 200 OK
Content-Type: application/json

{
  "header": {
    "status": 200,
    "title": "Timelogs Retrieved",
    "description": "Timelogs retrieved successfully"
  },
  "body": {
    "data": [
      {
        "id": 1001,
        "startTime": "2024-01-15T09:00:00Z",
        "stopTime": "2024-01-15T17:00:00Z",
        "spentHours": 8.0,
        "description": "Implemented user authentication module",
        "status": "approved",
        "project": {
          "id": 123,
          "name": "Client Portal Development"
        },
        "tasktype": {
          "id": 1,
          "name": "Development"
        }
      }
    ],
    "meta": {
      "pagination": {
        "current_page": 1,
        "last_page": 3,
        "per_page": 25,
        "total": 67,
        "from": 1,
        "to": 25
      }
    }
  }
}

API Security Implementation

Authentication Headers

Required Headers: 

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

App-to-App Headers (for integration APIs): 

galingsa: {app_source}
bulong: {encrypted_token}

Note: SSO authentication headers are not currently used as SSO is not actively implemented.

Rate Limiting

Rate Limit Headers: 

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
Retry-After: 60

Rate Limiting Rules: - General API: 100 requests per minute - Authentication: 60 requests per minute - App-to-app: 50 requests per minute - Bulk operations: 10 requests per minute

Input Validation

Validation Rules Example: 

// TimelogRequest validation
public function rules()
{
    return [
        'startTime' => 'required|date|before_or_equal:now',
        'stopTime' => 'required|date|after:startTime',
        'description' => 'required|string|min:10|max:1000',
        'project_user_id' => 'nullable|exists:project_users,id',
        'tasktype_id' => 'required|exists:tasktypes,id',
        'location' => 'nullable|string|max:255',
        'tags' => 'nullable|array',
        'tags.*' => 'string|max:50'
    ];
}

Specialized API Modules

SINOP Integration APIs

Base Path: /api/v2/sinop/

GET    /api/v2/sinop/setup             # Configuration
GET    /api/v2/sinop/users             # User analytics data
GET    /api/v2/sinop/projects          # Project analytics
GET    /api/v2/sinop/utilizations      # Utilization metrics
GET    /api/v2/sinop/projects/revenues-pm-percentages

Mobile API Access

Mobile Access Pattern: - No Dedicated Mobile Endpoints: Mobile applications use the same API routes as web - Responsive Web Interface: Mobile access through responsive web design - Same Authentication: Uses JWT authentication like web application - Shared Controllers: All endpoints accessible via mobile web interface

Reporting APIs

Report Generation: 

GET    /api/v2/reports/utilization     # Utilization reports
GET    /api/v2/reports/revenue         # Revenue reports
GET    /api/v2/reports/timesheet       # Timesheet reports
POST   /api/v2/reports/custom          # Custom report generation
GET    /api/v2/reports/{id}/download   # Download generated report

API Documentation and Testing

OpenAPI/Swagger Documentation

API Documentation Structure: 

openapi: 3.0.0
info:
  title: Stratpoint Timesheet API
  version: 2.0.0
  description: Comprehensive timesheet and project management API

servers:
  - url: https://timesheet.stratpoint.com/api/v2
    description: Production server
  - url: https://staging.timesheet.stratpoint.com/api/v2
    description: Staging server

paths:
  /timelogs:
    get:
      summary: List timelogs
      parameters:
        - name: start_date
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Successful response

API Testing

Postman Collection Structure: - Authentication tests - CRUD operation tests - Error handling tests - Performance tests - Integration tests

This comprehensive API structure provides a robust, scalable foundation for all client applications and integrations with the Stratpoint Timesheet Application.