Developer Integration Guide – Resource Planning API

1. Overview of the Data Model

This document explains how third‑party developers can integrate an external data source with the application. You configure your own API base URL, and the app's server proxies requests to your API.

The application works with three core entities:

• Resources – people or assets that can be assigned to projects. Minimum fields: id, name, email, capacity (decimal), and work_days (array of integers 1–7).
• Projects – initiatives resources can be scheduled against. Supported ields: id, title, optional note, color (any hex colot, but we recommend avoiding gray, red and green as these are colors we use for statuses).
• Assignments – link a resource to a project with a date range and a daily allocation. Fields: id, project_id, resource_id, date_from, date_to, hours_per_day, optional note.

2. API Endpoints

The server proxies requests to your configured apiBaseUrl. Endpoints should be relative to your API root and return JSON. You should have the following endpoints, so the app works correctly:

2.1 /loadData

On GET, should return all resources, projects, and assignments in a single payload:

{
  "resources": [
    {
      "id": 1,
      "name": "Alice",
      "email": "alice@example.com", // optional
      "capacity": 37.5,
      "work_days": [1, 2, 3, 4, 5]
    }
  ],
  "projects": [
    {
      "id": 42,
      "title": "Migration Project",
      "note": "Phase 1 rollout", // optional
      "color": '#D71DF4', // optional
      "enum_status_id": 1
    }
  ],
  "assignments": [
    {
      "id": 7,
      "project_id": 42,
      "resource_id": 1,
      "date_from": "2025-09-01",
      "date_to": "2025-09-10",
      "hours_per_day": 8,
      "note": "Polishing UI", // optional
    }
  ]
}

2.2 /resources

{
  "id": 1,
  "name": "Alice",
  "capacity": 37.5,
  "work_days": [1, 2, 3, 4, 5]
}

{
  "id": 1,
  "name": "Alice",
  "capacity": 37.5,
  "work_days": [1, 2, 3, 4, 5]
}

2.3 /projects

{
  "id": 42,
  "title": "Migration Project",
  "note": "Phase 1 rollout", // optional
  "color": '#D71DF4', // optional
}

{
  "id": 42,
  "title": "Migration Project",
  "note": "Phase 1 rollout", // optional
  "color": '#D71DF4', // optional
}

2.4 /assignments

{
  "id": 7,
  "project_id": 42,
  "resource_id": 1,
  "date_from": "2025-09-01",
  "date_to": "2025-09-10",
  "hours_per_day": 8,
  "note": "Polishing UI", // optional
}

{
  "id": 7,
  "project_id": 42,
  "resource_id": 1,
  "date_from": "2025-09-01",
  "date_to": "2025-09-10",
  "hours_per_day": 8,
  "note": "Polishing UI", // optional
}

3. Authentication & Workspace selection

Protect your API with authentication. The planner's server signs outbound requests with Authorization: Bearer <KEY>.

Since requests originate from our server to yours, typical browser CORS restrictions do not apply. Ensure your API allows requests from our deployment environment (standard server‑to‑server access).

4. Normalisation and Data Conversion

1. Dates: Provide ISO 8601 strings (YYYY-MM-DD). The client parses them to Dates.
2. Numbers: hours_per_day is converted to a float. Prefer dot as decimal separator.
3. IDs: Numeric IDs are accepted and coerced to strings internally.
4. Work days: work_days is an array of integers 1–7 (Mon–Sun).

5. Example Workflow

1. Initial data load – Client calls GET /loadData and normalises the response.
2. Creating a project – POST /projects;
3. Creating a resource – POST /resources;
4. Assigning a resource – POST /assignments; with respective resource_id and project_id.
5. Updating or deleting – PUT/DELETE the relevant entity. We do optimistic updates on client, but we show error messages on failure, so user can reload the page.