Skip to main content

BookWish API

RESTful API for the BookWish platform.

Base URL​

Production: https://api.bookwish.io/v1
Development: http://localhost:3000/v1

Authentication​

BookWish uses JWT tokens for authentication.

Getting Tokens​

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

Response:

{
  "accessToken": "eyJ...",
  "refreshToken": "eyJ...",
  "user": { ... }
}

Using Tokens​

Include the access token in the Authorization header:

Authorization: Bearer eyJ...

Refreshing Tokens​

POST /auth/refresh
Content-Type: application/json

{
  "refreshToken": "eyJ..."
}

API Structure​

Core Endpoints​

CategoryBase PathDescription
Auth/authAuthentication and account
Users/usersUser profiles and settings
Books/booksBook catalog and search
Wishlists/wishlistsWishlist management
Orders/ordersOrder processing
Stores/storesStore profiles

Social Endpoints​

CategoryBase PathDescription
Lines/linesShort posts about books
Reviews/reviewsBook reviews
Notes/notesPrivate reading notes
Follows/followsUser/store following

Store Operations​

CategoryBase PathDescription
Inventory/inventoryStore inventory
POS/posPoint of sale
Trade Credit/trade-creditTrade-in system

Programs​

CategoryBase PathDescription
Clubs/clubsBook clubs
Challenges/challengesReading challenges

Common Patterns​

Pagination​

List endpoints support cursor-based pagination:

GET /books?cursor=abc123&limit=20

Response includes:

{
  "data": [...],
  "nextCursor": "def456",
  "hasMore": true
}

Filtering​

Many endpoints support filtering:

GET /inventory?condition=used&category=fiction

Sorting​

Specify sort order:

GET /books?sort=title&order=asc

Response Format​

Success Response​

{
  "data": { ... },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Error Response​

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": { ... }
  }
}

Error Codes​

CodeHTTP StatusDescription
UNAUTHORIZED401Missing or invalid token
FORBIDDEN403Insufficient permissions
NOT_FOUND404Resource not found
VALIDATION_ERROR400Invalid request data
RATE_LIMITED429Too many requests
SERVER_ERROR500Internal server error

Rate Limiting​

API requests are rate limited:

TierLimit
Guest60/minute
Free120/minute
Premium300/minute
Bookstore600/minute

Rate limit headers:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1673789400

Webhooks​

BookWish can send webhooks for events:

  • Order status changes
  • Inventory updates
  • New followers

Configure webhooks in store settings.

SDKs​

Official SDKs:

  • Flutter/Dart: bookwish_api package
  • TypeScript: @bookwish/api-client

API Versioning​

The API is versioned via URL path:

/v1/books  - Current stable version
/v2/books  - Future version (when available)

Breaking changes result in new major versions.

Quick Reference​

GET /books?q=harry+potter

Add to Wishlist​

POST /wishlists/{id}/items
{
  "isbn": "9780143127741",
  "bookData": { ... }
}

Create Order​

POST /orders
{
  "items": [...],
  "fulfillmentType": "pickup",
  "storeId": "..."
}

Check Availability​

GET /books/availability?isbn=9780143127741

Support​

For API questions:

  • Check the detailed endpoint documentation
  • Review error messages and codes
  • Contact developer support