REST API

REST API

NexTask exposes a small REST API served by Fastify, running inside the Electron main process. The renderer consumes it through Axios; you can also call it directly during development.

• Base URL: http://localhost:3000 (configurable via VITE_BASE_URL)
• Interactive docs (Swagger UI): http://localhost:3000/docs
• Content type: application/json
• CORS: enabled for GET, POST, PUT, DELETE, PATCH

The server (src/main/server/index.ts) registers CORS, Swagger, the Swagger UI, and the task and stage route plugins, then listens on port 3000.

Swagger UI

Because every route declares a Fastify JSON schema, the OpenAPI spec is generated automatically. Open http://localhost:3000/docs while the app is running to browse and try every endpoint. The spec is titled nexTask API, version 1.0.2.

Endpoint summary

Tasks (Task tag)

Method	Path	Description
GET	/tasks	List all tasks (optionally filter by isHistorized)
GET	/tasks/:id	Get a single task
POST	/tasks	Create a task
PATCH	/tasks/:id	Update a task (partial)
PUT	/tasks/:id	Archive (historize) a task
DELETE	/tasks/:id	Delete a task
PATCH	/tasks/batch	Update many tasks in one transaction

Stages (Stage tag)

Method	Path	Description
GET	/stages	List all stages with their tasks
GET	/stages/:id	Get a single stage
POST	/stages	Create a stage
PATCH	/stages/:id	Update a stage (name / position)
DELETE	/stages/:id	Delete a stage
PATCH	/stages/batch	Update many stages in one transaction

---

Tasks

GET /tasks

Returns all tasks, ordered by stageId then position.

Query parameters

Name	Type	Description
isHistorized	boolean	Optional. If provided, filters to archived (true) or active (false) tasks. Omit to return all.

curl "http://localhost:3000/tasks?isHistorized=false"

GET /tasks/:id

Returns a single task, or 404 if not found.

curl http://localhost:3000/tasks/1

POST /tasks

Creates a task.

Body (required: stageId, position, title, version, description)

{
  "stageId": 1,
  "position": 0,
  "title": "Write the wiki",
  "version": "1.5.0",
  "description": "Document the whole project"
}

Returns the created task (200).

PATCH /tasks/:id

Partially updates a task. Any subset of these fields may be sent:

{
  "title": "New title",
  "version": "1.5.0",
  "description": "…",
  "position": 2,
  "stageId": 3,
  "isHistorized": false,
  "historizationDate": null
}

Returns the updated task, or 404 if it does not exist.

PUT /tasks/:id — archive

Marks a task as historized (archived): sets isHistorized = true, stamps historizationDate, and clears stageId. This is what the board's "trash" button triggers.

curl -X PUT http://localhost:3000/tasks/1

Response:

{ "message": "Tâche 1 marquée comme historisée" }

DELETE /tasks/:id

Permanently deletes a task. Returns { "message": "Tâche supprimée" } or 404.

PATCH /tasks/batch

Updates many tasks atomically (a single Prisma $transaction). Used by drag-and-drop to persist new positions/columns in one call.

Body: an array of objects, each requiring id:

[
  { "id": 1, "position": 0, "stageId": 2 },
  { "id": 2, "position": 1, "stageId": 2 }
]

Returns the array of updated tasks. Responds 400 if the array is empty, 500 on failure.

ℹ️ The static route /tasks/batch is intentionally distinct from the parameterized /tasks/:id; Fastify's router resolves the static path first.

---

Stages

GET /stages

Returns all stages, each including its tasks, ordered by id then position. This is the endpoint the board uses on load — the renderer derives the full task list from it in one round-trip.

curl http://localhost:3000/stages

GET /stages/:id

Returns a single stage, or 404.

POST /stages

Creates a stage.

Body (required: name, position)

{ "name": "Backlog", "position": 5 }

PATCH /stages/:id

Updates a stage's name and/or position. Returns the updated stage, or 404.

DELETE /stages/:id

Deletes a stage. At the database level, its tasks' stageId is set to NULL (ON DELETE SET NULL). Returns { "message": "Stage supprimée" } or 404.

In the UI, deleting a stage additionally archives its active tasks first (handled in the Stage store, not the API). See Frontend.

PATCH /stages/batch

Updates many stages atomically (used when reordering columns via drag-and-drop).

Body: array of objects, each requiring id:

[
  { "id": 1, "position": 1 },
  { "id": 2, "position": 0 }
]

Returns the updated stages. Responds 400 if empty, 500 on failure.

---

Error format

Errors are returned as a JSON object with an error message and the corresponding HTTP status:

{ "error": "Tâche non trouvée" }

Status	Meaning
200	Success
400	Bad request (e.g. empty batch array)
404	Resource not found
500	Server-side failure

The Axios wrapper (src/renderer/utils/api.helper.ts) rethrows non-2xx responses as Error objects containing the status, status text and body — so store actions can catch and log them.

Related pages

• Data model behind these endpoints: Database
• How the UI calls them and caches results: Frontend