Tracking API (Habits)

Service: Tracking Service
Base Path: /api/v1/habits

The Tracking Service manages the lifecycle of habits. A habit belongs to an avatar and has a recurrence schedule (daily, weekly, or monthly). Attending a habit records a completion event and triggers gamification rewards via domain events.

---

Endpoints

Create Habit

POST /api/v1/habits

Creates a new habit for an avatar.

Request body:

{
  "avatarId": "string",
  "title": "string",
  "description": "string",
  "recurrenceType": "DAILY | WEEKLY | MONTHLY",
  "dayOfWeek": "MONDAY",
  "dayOfMonth": 1
}

Field	Required	Notes
avatarId	Yes
title	Yes
description	No
recurrenceType	Yes	DAILY, WEEKLY, or MONTHLY
dayOfWeek	Conditional	Required when recurrenceType is WEEKLY
dayOfMonth	Conditional	Required when recurrenceType is MONTHLY

Response 200 OK:

{
  "id": "string",
  "_links": { ... }
}

---

Get Habit

GET /api/v1/habits/{id}

Returns full habit details.

Response 200 OK:

{
  "id": "string",
  "avatarId": "string",
  "title": "string",
  "description": "string",
  "tags": ["health", "exercise"],
  "recurrence": {
    "type": "WEEKLY",
    "dayOfMonth": null,
    "dayOfWeek": "MONDAY"
  },
  "lastAttendedDate": "2024-01-15T08:00:00",
  "nextRecurrenceDate": "2024-01-22T08:00:00",
  "associatedQuestId": "string | null",
  "_links": { ... }
}

---

Delete Habit

DELETE /api/v1/habits/{id}

Permanently deletes the habit.

Response 204 No Content

---

Habit Properties

Get Title

GET /api/v1/habits/{id}/title

{ "title": "Morning Run" }

Update Title

PATCH /api/v1/habits/{id}/title

Request body:

{ "title": "Morning Run" }

Response 204 No Content

---

Get Description

GET /api/v1/habits/{id}/description

{ "description": "Run 5km every morning." }

Update Description

PATCH /api/v1/habits/{id}/description

Request body:

{ "description": "Run 5km every morning." }

Response 204 No Content

---

Get Tags

GET /api/v1/habits/{id}/tags

{ "tags": ["health", "fitness"] }

Update Tags

PATCH /api/v1/habits/{id}/tags

Request body:

{ "tags": ["health", "fitness", "outdoor"] }

Response 204 No Content

---

Get Recurrence

GET /api/v1/habits/{id}/recurrence

{
  "type": "WEEKLY",
  "dayOfMonth": null,
  "dayOfWeek": "MONDAY"
}

Update Recurrence

PATCH /api/v1/habits/{id}/recurrence

Request body:

{
  "type": "MONTHLY",
  "dayOfWeek": null,
  "dayOfMonth": 15
}

Response 204 No Content

---

Get Last Attended Date

GET /api/v1/habits/{id}/last-attended-date

{ "date": "2024-01-15T08:00:00" }

---

Get History

GET /api/v1/habits/{id}/history

Returns the full completion history of the habit.

{
  "history": [
    { "date": "2024-01-08T08:00:00" }
  ]
}

---

Attending a Habit

Mark Habit as Attended

POST /api/v1/habits/{id}/attend

Records a habit completion event. This triggers gamification domain events (XP reward, etc.).

Request body:

{ "date": "2024-01-15T08:00:00" }

Response 204 No Content

---

Error Responses

Status	Condition
400 Bad Request	Invalid recurrence configuration or business rule violation
404 Not Found	Habit not found