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. The app lets you specify your own API base URL (e.g., https://x8ki-letl-twmt.n7.xano.io/api:BngaZ0Mv) so it can pull and push data from your system instead of the default backend. While the examples assume a relational/SQL backend, the same concepts apply to NoSQL as long as responses follow the formats below.

The application works with three core entities:

• Resources – people or assets that can be assigned to projects. Minimum fields: id, name, email, capacity (decimal), andwork_days (array of integers 1–7).
• Projects – initiatives resources can be scheduled against. Typical fields: id, title, optional note, color (numeric id), and enum_status_id.
• 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.

The client normalises common SQL snake_case fields to camelCase:

Camel‑cased properties are also accepted. If nested objects (project, resource) are returned, the client derivesprojectId and resourceId automatically.

2. API Endpoints

The client prefixes all requests with the configuredapiBaseUrl. Endpoints should be relative to your API root and must return JSON with appropriate CORS headers.

2.1 GET /loadData

Return all resources, projects, and assignments in a single payload:

{
  "resources": [
    {
      "id": 1,
      "name": "Alice",
      "email": "alice@example.com",
      "capacity": 37.5,
      "work_days": [1, 2, 3, 4, 5]
    }
  ],
  "projects": [
    {
      "id": 42,
      "title": "Migration Project",
      "note": "Phase 1 rollout",
      "color": 3,
      "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": "Overtime"
    }
  ]
}

Property names may be snake_case or camelCase; the client normalises them.

2.2 /resources

2.3 /projects

2.4 /assignments

2.5 Optional enumeration endpoints

• GET /enum_colors – list of colours with id and color string (e.g. #E91E63)
• GET /enum_status – list of statuses with id and a human‑readable title

3. Authentication & Workspace selection

Protect your API with your own authentication. Because the planner runs in the browser and calls your API directly, configure CORS to allow requests from your domain.

Each workspace stores an apiBaseUrl. Scope your data per workspace (e.g., via workspace IDs or tenant‑specific base URLs).

4. Normalisation and Data Conversion

• Dates: Provide ISO 8601 strings (YYYY-MM-DD orYYYY-MM-DDTHH:MM:SSZ). The client parses them to Dates.
• Numbers: hours_per_day is converted to a float. Prefer dot as decimal separator.
• IDs: Numeric IDs are accepted and coerced to strings internally.
• Work days: work_days is an array of integers 1–7 (Mon–Sun). If omitted, the client assumes Mon–Fri.

5. Example Workflow

1. Initial data load – Client calls GET /loadData and normalises the response.
2. Creating a project – POST /projects; on success, the client inserts it into local state.
3. Assigning a resource – POST /assignments; on success, the client adds it to the grid immediately.
4. Updating or deleting – PUT/PATCH/DELETE the relevant entity and update local cache on success.

6. Summary

By exposing the endpoints above and returning JSON in the expected format, you can plug your own database into the planner. The client normalises both SQL‑style and Mongo‑style payloads, so you do not need to mirror internal models; just provide the required fields and consistent date/number formats. Enable CORS and add authentication as appropriate for your environment.