Overview
This document defines the RESTful API specification for the Book Sale platform. It covers
authentication, user management, book listings, search, optional in-app payments, and
integration with the Delivery API (developed separately by Applift Labs).
Authentication
Mechanism: JWT Bearer Tokens
● Register: POST /auth/register
Body:
{
"name": "string",
"email": "string (email)",
"password": "string (min 8 chars)"
}
○
○ Responses:
■ 201 Created: { "token": "jwt-token", "user": { ... } }
■ 400 Bad Request: validation errors
● Login: POST /auth/login
Body:
{
"email": "string",
"password": "string"
}
○
○ Responses:
■ 200 OK: { "token": "jwt-token", "user": { ... } }
■ 401 Unauthorized: invalid credentials
● Get Profile: GET /auth/me
○ Headers: Authorization: Bearer <token>
○ Response:
■ 200 OK: { "id": "uuid", "name": "string", "email":
"string" }
User Management
Get User by ID
● Endpoint: GET /users/{userId}
● Auth: Bearer Token
● Response:
200 OK:
{
"id": "uuid",
"name": "string",
"email": "string",
"joinedAt": "ISO-8601"
}
○
○ 404 Not Found
Book Listings
Book Entity Schema
{
"id": "uuid",
"title": "string",
"author": "string",
"isbn": "string",
"description": "string",
"coverUrl": "url",
"createdAt": "ISO-8601",
"updatedAt": "ISO-8601"
}
Listing Entity Schema
{
"id": "uuid",
"book": { /* Book Entity */ },
"sellerId": "uuid",
"price": "number (in cents)",
"condition": "enum: ["new","like_new","used_good","used_fair"]",
"status": "enum: ["available","pending","sold"]",
"createdAt": "ISO-8601",
"updatedAt": "ISO-8601"
}
Endpoints
Operation Method Path Auth Description
List all listings GET /listings Optional Query: page, limit,
(paginated) author, title
View single listing GET /listings/{listingId} Optional
Create a new listing POST /listings Require Body: Listing create
d payload
Update an existing PUT /listings/{listingId} Require Body: Fields to update
listing d
Delete a listing DELETE /listings/{listingId} Require
d
Create Listing
Body:
{
"bookId": "uuid",
"price": 1500,
"condition": "used_good"
}
●
● Responses:
○ 201 Created: Listing object
○ 400 Bad Request
○ 401 Unauthorized
Search
● Endpoint: GET /search
● Query Parameters:
○ q: search term (title, author, ISBN)
○ page, limit
● Response:
○ 200 OK: { "results": [Listing], "total": number }
Payments (Optional)
In-app payments are optional. If user chooses to pay via the app, the following endpoints apply.
Initiate Payment
● Endpoint: POST /payments/initiate
● Auth: Bearer Token
Body:
{
"listingId": "uuid",
"paymentMethod": "string (e.g., stripe)",
"amount": number
}
●
● Response:
○ 200 OK: { "paymentId": "uuid", "paymentUrl": "string" }
Payment Status
● Endpoint: GET /payments/{paymentId}/status
● Auth: Bearer Token
● Response:
○ 200 OK: { "status": "pending|completed|failed" }
Delivery Integration
Delivery is handled by a separate Applift Labs Delivery API. The backend should call:
● Create Delivery Order
○ Endpoint: POST /api/delivery/orders
Body:
{
"orderId": "uuid", // listing or payment reference
"pickupAddress": "string",
"dropoffAddress": "string",
"recipientName": "string",
"recipientPhone": "string"
}
○
Response:
{
"deliveryId": "uuid",
"status": "created",
"expectedPickup": "ISO-8601"
}
○
● Get Delivery Status
○ Endpoint: GET /api/delivery/orders/{deliveryId}
Response:
{ "deliveryId": "uuid", "status": "in_transit|delivered|cancelled" }
○
Common Error Responses
{
"error": {
"code": "string",
"message": "string"
}
}
HTTP Code Meaning Example Codes
400 Bad Request VALIDATION_ERROR
401 Unauthorized INVALID_TOKEN
403 Forbidden INSUFFICIENT_PERMISSIONS
404 Not Found RESOURCE_NOT_FOUND
500 Internal Server Error SERVER_ERROR
Notes
1. All timestamps in ISO-8601 UTC.
2. Use standard HTTP status codes.
3. Responses should follow JSON:API conventions where possible.
4. Ensure CORS is configured to allow frontend domain.
End of Specification