Wishlists API

Endpoints for managing user wishlists and wishlist items.

Get User's Wishlists

Get all wishlists for the authenticated user.

GET /wishlists

Authentication

Required (Bearer token)

Response

{
  "wishlists": [
    {
      "id": "990e8400-e29b-41d4-a716-446655440004",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Summer Reading List",
      "description": "Books to read this summer",
      "isPublic": true,
      "itemCount": 12,
      "createdAt": "2024-03-01T08:00:00Z",
      "updatedAt": "2024-03-15T14:20:00Z"
    },
    {
      "id": "990e8400-e29b-41d4-a716-446655440005",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Gift Ideas",
      "description": "Books to ask for as gifts",
      "isPublic": false,
      "itemCount": 5,
      "createdAt": "2024-02-10T10:30:00Z",
      "updatedAt": "2024-03-12T09:15:00Z"
    }
  ]
}

Errors

401 Unauthorized - Not authenticated
500 InternalServerError - Server error

Example

curl "https://api.bookwish.app/wishlists" \
  -H "Authorization: Bearer YOUR_TOKEN"

Create Wishlist

Create a new wishlist.

POST /wishlists

Authentication

Required (Bearer token)

Tier Limits

Free: 1 wishlist
Premium: 10 wishlists
Bookstore: Unlimited

Request Body

{
  "name": "Science Fiction Classics",
  "description": "Must-read sci-fi books",
  "isPublic": true
}

Response

{
  "id": "990e8400-e29b-41d4-a716-446655440006",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Science Fiction Classics",
  "description": "Must-read sci-fi books",
  "isPublic": true,
  "itemCount": 0,
  "createdAt": "2024-03-20T11:45:00Z",
  "updatedAt": "2024-03-20T11:45:00Z"
}

Errors

400 ValidationError - Invalid request body
401 Unauthorized - Not authenticated
403 Forbidden - Tier limit reached
500 InternalServerError - Server error

Example

curl -X POST "https://api.bookwish.app/wishlists" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Science Fiction Classics",
    "description": "Must-read sci-fi books",
    "isPublic": true
  }'

Get Wishlist by ID

Get a specific wishlist by ID.

GET /wishlists/:id

Authentication

Optional (Bearer token - required for private wishlists)

Path Parameters

id - Wishlist ID

Response

{
  "id": "990e8400-e29b-41d4-a716-446655440004",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "username": "johndoe",
    "displayName": "John Doe",
    "avatarUrl": "https://cdn.bookwish.app/avatars/johndoe.jpg"
  },
  "name": "Summer Reading List",
  "description": "Books to read this summer",
  "isPublic": true,
  "itemCount": 12,
  "items": [
    {
      "id": "item-001",
      "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
      "book": {
        "id": "bb0e8400-e29b-41d4-a716-446655440006",
        "isbn": "9780316769174",
        "title": "The Catcher in the Rye",
        "authors": ["J.D. Salinger"],
        "coverUrl": "https://covers.bookwish.app/9780316769174.jpg",
        "averageRating": 4.5
      },
      "priority": 1,
      "notes": "Highly recommended by Sarah",
      "addedAt": "2024-03-05T12:00:00Z"
    }
  ],
  "createdAt": "2024-03-01T08:00:00Z",
  "updatedAt": "2024-03-15T14:20:00Z"
}

Errors

401 Unauthorized - Private wishlist requires authentication
403 Forbidden - Cannot access private wishlist
404 NotFound - Wishlist not found
500 InternalServerError - Server error

Example

curl "https://api.bookwish.app/wishlists/990e8400-e29b-41d4-a716-446655440004"

Update Wishlist

Update wishlist details.

PUT /wishlists/:id

Authentication

Required (Bearer token)

Path Parameters

id - Wishlist ID

Request Body

{
  "name": "Updated Summer Reading",
  "description": "Curated summer book collection",
  "isPublic": false
}

Response

{
  "id": "990e8400-e29b-41d4-a716-446655440004",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Updated Summer Reading",
  "description": "Curated summer book collection",
  "isPublic": false,
  "itemCount": 12,
  "createdAt": "2024-03-01T08:00:00Z",
  "updatedAt": "2024-03-21T10:15:00Z"
}

Errors

400 ValidationError - Invalid request body
401 Unauthorized - Not authenticated
403 Forbidden - Not the wishlist owner
404 NotFound - Wishlist not found
500 InternalServerError - Server error

Example

curl -X PUT "https://api.bookwish.app/wishlists/990e8400-e29b-41d4-a716-446655440004" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Summer Reading",
    "isPublic": false
  }'

Delete Wishlist

Delete a wishlist and all its items.

DELETE /wishlists/:id

Authentication

Required (Bearer token)

Path Parameters

id - Wishlist ID

Response

{
  "success": true,
  "message": "Wishlist deleted successfully"
}

Errors

401 Unauthorized - Not authenticated
403 Forbidden - Not the wishlist owner
404 NotFound - Wishlist not found
500 InternalServerError - Server error

Example

curl -X DELETE "https://api.bookwish.app/wishlists/990e8400-e29b-41d4-a716-446655440004" \
  -H "Authorization: Bearer YOUR_TOKEN"

Add Item to Wishlist

Add a book to a wishlist.

POST /wishlists/:id/items

Authentication

Required (Bearer token)

Path Parameters

id - Wishlist ID

Request Body

{
  "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
  "priority": 1,
  "notes": "Recommended by book club"
}

Response

{
  "id": "item-002",
  "wishlistId": "990e8400-e29b-41d4-a716-446655440004",
  "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
  "book": {
    "id": "bb0e8400-e29b-41d4-a716-446655440006",
    "isbn": "9780316769174",
    "title": "The Catcher in the Rye",
    "authors": ["J.D. Salinger"],
    "coverUrl": "https://covers.bookwish.app/9780316769174.jpg"
  },
  "priority": 1,
  "notes": "Recommended by book club",
  "addedAt": "2024-03-21T14:30:00Z"
}

Errors

400 ValidationError - Invalid request body or book already in wishlist
401 Unauthorized - Not authenticated
403 Forbidden - Not the wishlist owner
404 NotFound - Wishlist or book not found
500 InternalServerError - Server error

Example

curl -X POST "https://api.bookwish.app/wishlists/990e8400-e29b-41d4-a716-446655440004/items" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
    "priority": 1,
    "notes": "Recommended by book club"
  }'

Update Wishlist Item

Update an item's priority or notes.

PUT /wishlists/:id/items/:itemId

Authentication

Required (Bearer token)

Path Parameters

id - Wishlist ID
itemId - Wishlist item ID

Request Body

{
  "priority": 2,
  "notes": "Updated: Must read before summer ends"
}

Response

{
  "id": "item-002",
  "wishlistId": "990e8400-e29b-41d4-a716-446655440004",
  "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
  "priority": 2,
  "notes": "Updated: Must read before summer ends",
  "addedAt": "2024-03-21T14:30:00Z",
  "updatedAt": "2024-03-22T09:00:00Z"
}

Errors

400 ValidationError - Invalid request body
401 Unauthorized - Not authenticated
403 Forbidden - Not the wishlist owner
404 NotFound - Wishlist or item not found
500 InternalServerError - Server error

Example

curl -X PUT "https://api.bookwish.app/wishlists/990e8400-e29b-41d4-a716-446655440004/items/item-002" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "priority": 2,
    "notes": "Updated: Must read before summer ends"
  }'

Remove Item from Wishlist

Remove a book from a wishlist.

DELETE /wishlists/:id/items/:itemId

Authentication

Required (Bearer token)

Path Parameters

id - Wishlist ID
itemId - Wishlist item ID

Response

{
  "success": true,
  "message": "Item removed from wishlist"
}

Errors

401 Unauthorized - Not authenticated
403 Forbidden - Not the wishlist owner
404 NotFound - Wishlist or item not found
500 InternalServerError - Server error

Example

curl -X DELETE "https://api.bookwish.app/wishlists/990e8400-e29b-41d4-a716-446655440004/items/item-002" \
  -H "Authorization: Bearer YOUR_TOKEN"

Wishlist Object Fields

Field	Type	Description
`id`	string	Unique wishlist identifier (UUID)
`userId`	string	Owner's user ID
`name`	string	Wishlist name
`description`	string	Wishlist description
`isPublic`	boolean	Whether wishlist is publicly visible
`itemCount`	number	Number of items in wishlist
`createdAt`	string	Creation timestamp (ISO 8601)
`updatedAt`	string	Last update timestamp (ISO 8601)

Wishlist Item Object Fields

Field	Type	Description
`id`	string	Unique item identifier
`wishlistId`	string	Parent wishlist ID
`bookId`	string	Book ID
`book`	object	Book details object
`priority`	number	Item priority (1=highest)
`notes`	string	User notes about this item
`addedAt`	string	When item was added (ISO 8601)
`updatedAt`	string	Last update timestamp (ISO 8601)

Get User's Wishlists​

Authentication​

Response​

Errors​

Example​

Create Wishlist​

Authentication​

Tier Limits​

Request Body​

Response​

Errors​

Example​

Get Wishlist by ID​

Authentication​

Path Parameters​

Response​

Errors​

Example​

Update Wishlist​

Authentication​

Path Parameters​

Request Body​

Response​

Errors​

Example​

Delete Wishlist​

Authentication​

Path Parameters​

Response​

Errors​

Example​

Add Item to Wishlist​

Authentication​

Path Parameters​

Request Body​

Response​

Errors​

Example​

Update Wishlist Item​

Authentication​

Path Parameters​

Request Body​

Response​

Errors​

Example​

Remove Item from Wishlist​

Authentication​

Path Parameters​

Response​

Errors​

Example​

Wishlist Object Fields​

Wishlist Item Object Fields​

Get User's Wishlists

Authentication

Response

Errors

Example

Create Wishlist

Authentication

Tier Limits

Request Body

Response

Errors

Example

Get Wishlist by ID

Authentication

Path Parameters

Response

Errors

Example

Update Wishlist

Authentication

Path Parameters

Request Body

Response

Errors

Example

Delete Wishlist

Authentication

Path Parameters

Response

Errors

Example

Add Item to Wishlist

Authentication

Path Parameters

Request Body

Response

Errors

Example

Update Wishlist Item

Authentication

Path Parameters

Request Body

Response

Errors

Example

Remove Item from Wishlist

Authentication

Path Parameters

Response

Errors

Example

Wishlist Object Fields

Wishlist Item Object Fields