Favorites

Endpoints for managing user favorites in the application. These endpoints allow users to view their favorite items and add new items to their favorites list. The system supports favoriting various types of content including letters, affirmations, open questions, and deconstruction questions.

Favorites are paginated and sorted by creation date, showing the most recent favorites first. Each favorite item includes information about the original content and its associated intention.

List Favorites

Retrieve a paginated list of all items that the authenticated user has marked as favorites. The list includes various types of favorites (letters, affirmations, open questions, and deconstruction questions) sorted by creation date, with the most recent favorites appearing first.

Each favorite item in the response includes:

• The original item's name and ID
• The associated intention
• The favorite's creation date
• Pagination information for easy navigation

Endpoint

• Method: GET
• URL: /api/home/favorites

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes
Authorization	Bearer YOUR_API_TOKEN	Yes

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number for pagination (default: 1)
per_page	integer	No	Number of items per page (default: 10)

Success Response

{
    "success": true,
    "message": "resource fetched successfully.",
    "data": {
        "current_page": 1,
        "first_page_url": "http://127.0.0.1:8000/api/home/favorites?page=1",
        "from": 1,
        "last_page": 2,
        "last_page_url": "http://127.0.0.1:8000/api/home/favorites?page=2",
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/home/favorites?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": "http://127.0.0.1:8000/api/home/favorites?page=2",
                "label": "2",
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/home/favorites?page=2",
                "label": "Next »",
                "active": false
            }
        ],
        "next_page_url": "http://127.0.0.1:8000/api/home/favorites?page=2",
        "path": "http://127.0.0.1:8000/api/home/favorites",
        "per_page": 10,
        "prev_page_url": null,
        "to": 10,
        "total": 14,
        "favorites": [
            {
                "id": 1,
                "favouritable_name": "Sample favorite item",
                "favouritable_id": 4,
                "intention_name": "Career Growth",
                "is_favorite": true,
                "created_at": "2024 فبراير 21"
            }
        ]
    },
    "status_code": 200
}

Add to Favorites

Add a new item to the user's favorites list. You can favorite different types of content:

• Letters: Inspirational or meaningful letters
• Affirmations: Positive statements and affirmations
• Open Questions: Questions for reflection and growth
• Deconstruction Questions: Questions that help break down complex thoughts

When an item is favorited:

• It becomes accessible from the user's favorites list
• The system tracks the favorite's creation date
• The item is associated with its original intention

Endpoint

• Method: POST
• URL: /api/home/favorites

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes
Authorization	Bearer YOUR_API_TOKEN	Yes

Request Body Parameters

Parameter	Type	Required	Description
id	integer	Yes	ID of the item to favorite
type	string	Yes	Type of item to favorite (letter/affirmation/open_question/deconstruction_question)

Success Response

{
    "success": true,
    "message": "Item added to favorites successfully",
    "data": {
        "id": 1,
        "favouritable_name": "Sample favorite item",
        "favouritable_id": 4,
        "intention_name": "Career Growth",
        "is_favorite": true,
        "created_at": "2024 فبراير 21"
    },
    "status_code": 200
}

Error Responses

Not Found (404)

{
    "success": false,
    "message": "Item not found",
    "data": null,
    "status_code": 404
}

Already Favorited (422)

{
    "success": false,
    "message": "Item is already in favorites",
    "data": null,
    "status_code": 422
}

Remove from Favorites

Remove an item from the user's favorites list. This endpoint allows users to unfavorite any previously favorited item. The operation:

• Removes the item from the user's favorites list
• Preserves the original item in the system
• Updates any related counters or statistics

When an item is removed from favorites:

• The item is no longer accessible from the user's favorites list
• The original item remains unchanged in the system
• All associated favorite metadata is cleaned up
• Related counters and statistics are updated

Endpoint

• Method: DELETE
• URL: /api/home/favorites/{id}

Where {id} is the ID of the favorite item to remove.

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes
Authorization	Bearer YOUR_API_TOKEN	Yes

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes
Authorization	Bearer YOUR_API_TOKEN	Yes

URL Parameters

Parameter	Type	Required	Description
id	integer	Yes	ID of the favorite item to remove

Success Response

{
    "success": true,
    "message": "Item removed from favorites successfully",
    "data": null,
    "status_code": 200
}

Error Responses

Not Found (404)

{
    "success": false,
    "message": "Favorite not found",
    "data": null,
    "status_code": 404
}

Unauthorized (401)

{
    "success": false,
    "message": "Unauthorized access",
    "data": null,
    "status_code": 401
}

Forbidden (403)

{
    "success": false,
    "message": "You don't have permission to remove this favorite",
    "data": null,
    "status_code": 403
}

Example Implementation Flow

1. Get the user's API token from storage
2. To list favorites:
   • Make GET request to /api/home/favorites
   • Display favorites in appropriate UI sections
3. To add to favorites:
   • Determine the type of item (letter/affirmation/question)
   • Make POST request to the appropriate endpoint (e.g., /api/home/letter/{id}/favorite)
   • Update UI to show item is favorited
4. To remove from favorites:
   • Make DELETE request to /api/home/favorites/{id}
   • Update UI to show item is no longer favorited
5. Handle errors:
   • If unauthorized, redirect to login
   • Show appropriate error messages
   • Update UI state accordingly