Digital Library API

CMPS312 Assignment 4 • Qatar University

A comprehensive RESTful API for managing a digital library system with books, authors, members, staff, and transactions. Built with Next.js 15, PostgreSQL, and Prisma ORM.

🌐Base URL

Production API Endpoint

https://digital-library-api.vercel.app

📖How to Use cURL

cURL is a command-line tool for making HTTP requests. It comes pre-installed on macOS, Linux, and Windows 10+. Use it to test API endpoints directly from your terminal.

Basic Usage:

  • •GET Request: Simply copy and paste the cURL command in your terminal
  • •POST/PUT Requests: Include the -d flag with JSON data
  • •Headers: Use -H to specify Content-Type and other headers

Quick Example:

# Open your terminal and run:
curl -X GET https://digital-library-api.vercel.app/api/authors

# You'll see JSON response with all authors!

💡 Tip: For better formatting, pipe the output through jq or use | python -m json.tool to pretty-print JSON responses.

🔐Authentication

POST/api/auth

Authenticate staff member with username and password

Request Body:

{
  "username": "admin",
  "password": "admin123"
}

Response (200 OK):

{
  "staffId": "S001",
  "username": "admin",
  "fullName": "Admin User",
  "role": "admin"
}

💻cURL Example:

curl -X POST https://digital-library-api.vercel.app/api/auth \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'

👤Authors Endpoints

GET/api/authors

Get all authors in the library

Response (200 OK):

[
  {
    "id": "auth001",
    "name": "J.K. Rowling",
    "biography": "British author...",
    "birthYear": 1965
  }
]

💻 cURL Example:

curl -X GET https://digital-library-api.vercel.app/api/authors
GET/api/authors/:id

Get a specific author by ID

Response (200 OK):

{
  "id": "auth001",
  "name": "J.K. Rowling",
  "biography": "British author...",
  "birthYear": 1965
}
POST/api/authors

Create a new author

Request Body:

{
  "id": "auth008",
  "name": "New Author",
  "biography": "Biography text",
  "birthYear": 1980
}

Response (201 Created):

{
  "id": "auth008",
  "name": "New Author",
  "biography": "Biography text",
  "birthYear": 1980
}

💻 cURL Example:

curl -X POST https://digital-library-api.vercel.app/api/authors \
  -H "Content-Type: application/json" \
  -d '{
    "id": "auth008",
    "name": "New Author",
    "biography": "Biography text",
    "birthYear": 1980
  }'
PUT/api/authors/:id

Update an existing author

Request Body:

{
  "name": "Updated Name",
  "biography": "Updated biography",
  "birthYear": 1980
}
DELETE/api/authors/:id

Delete an author from the library

Response (200 OK):

{
  "message": "Author deleted successfully"
}

📚Books Endpoints

GET/api/books

Get all books (optional: filter by authorId)

Query Parameters (optional):

?authorId=auth001  // Filter by author

Response (200 OK):

[
  {
    "id": "book001",
    "title": "Harry Potter and the Philosopher's Stone",
    "authorId": "auth001",
    "publishedYear": 1997,
    "category": "Fantasy",
    "isAvailable": true
  }
]

💻 cURL Example:

# Get all books
curl -X GET https://digital-library-api.vercel.app/api/books

# Get books by author
curl -X GET "https://digital-library-api.vercel.app/api/books?authorId=auth001"
GET/api/books/:id

Get a specific book by ID

Response (200 OK):

{
  "id": "book001",
  "title": "Harry Potter and the Philosopher's Stone",
  "authorId": "auth001",
  "publishedYear": 1997,
  "category": "Fantasy",
  "isAvailable": true
}
POST/api/books

Add a new book to the library

Request Body:

{
  "id": "book009",
  "title": "New Book",
  "authorId": "auth001",
  "publishedYear": 2024,
  "category": "Fiction",
  "isbn": "978-1234567890",
  "pageCount": 350,
  "publisher": "Publisher Name"
}

Response (201 Created):

{
  "id": "book009",
  "title": "New Book",
  "authorId": "auth001",
  "publishedYear": 2024,
  "category": "Fiction",
  "isAvailable": true
}

💻 cURL Example:

curl -X POST https://digital-library-api.vercel.app/api/books \
  -H "Content-Type: application/json" \
  -d '{
    "id": "book009",
    "title": "New Book",
    "authorId": "auth001",
    "publishedYear": 2024,
    "category": "Fiction",
    "isbn": "978-1234567890",
    "pageCount": 350,
    "publisher": "Publisher Name"
  }'
PUT/api/books/:id

Update book information

Request Body:

{
  "title": "Updated Title",
  "isAvailable": false
}
DELETE/api/books/:id

Remove a book from the library

Response (200 OK):

{
  "message": "Book deleted successfully"
}

👥Members Endpoints

GET/api/members

Get all library members

Response (200 OK):

[
  {
    "id": "M001",
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "phone": "+974-1234-5678",
    "memberType": "student"
  }
]

💻 cURL Example:

curl -X GET https://digital-library-api.vercel.app/api/members
GET/api/members/:id

Get a specific member by ID (includes transaction history)

Response (200 OK):

{
  "id": "M001",
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "phone": "+974-1234-5678",
  "memberType": "student",
  "transactions": [...]
}
POST/api/members

Register a new library member

Request Body:

{
  "id": "M007",
  "name": "New Member",
  "email": "newmember@example.com",
  "phone": "+974-9999-9999",
  "memberType": "student"
}

Response (201 Created):

{
  "id": "M007",
  "name": "New Member",
  "email": "newmember@example.com",
  "phone": "+974-9999-9999",
  "memberType": "student"
}

💻 cURL Example:

curl -X POST https://digital-library-api.vercel.app/api/members \
  -H "Content-Type: application/json" \
  -d '{
    "id": "M007",
    "name": "New Member",
    "email": "newmember@example.com",
    "phone": "+974-9999-9999",
    "memberType": "student"
  }'
PUT/api/members/:id

Update member information

Request Body:

{
  "name": "Updated Name",
  "email": "updated@example.com",
  "memberType": "faculty"
}
DELETE/api/members/:id

Remove a member from the system

Response (200 OK):

{
  "message": "Member deleted successfully"
}

👔Staff Endpoints

GET/api/staff

Get all staff members

Response (200 OK):

[
  {
    "staffId": "S001",
    "username": "admin",
    "fullName": "Admin User",
    "role": "admin"
  }
]

💻 cURL Example:

curl -X GET https://digital-library-api.vercel.app/api/staff
GET/api/staff/:id

Get a specific staff member by ID

Response (200 OK):

{
  "staffId": "S001",
  "username": "admin",
  "fullName": "Admin User",
  "role": "admin"
}
POST/api/staff

Add a new staff member

Request Body:

{
  "staffId": "S004",
  "username": "newstaff",
  "password": "password123",
  "fullName": "New Staff",
  "role": "staff"
}

Response (201 Created):

{
  "staffId": "S004",
  "username": "newstaff",
  "fullName": "New Staff",
  "role": "staff"
}

💻 cURL Example:

curl -X POST https://digital-library-api.vercel.app/api/staff \
  -H "Content-Type: application/json" \
  -d '{
    "staffId": "S004",
    "username": "newstaff",
    "password": "password123",
    "fullName": "New Staff",
    "role": "staff"
  }'
PUT/api/staff/:id

Update staff member information

Request Body:

{
  "username": "updatedusername",
  "fullName": "Updated Name",
  "role": "librarian"
}
DELETE/api/staff/:id

Remove a staff member

Response (200 OK):

{
  "message": "Staff deleted successfully"
}

🔄Transactions Endpoints

GET/api/transactions

Get all transactions (supports filtering by memberId or bookId)

Query Parameters (optional):

?memberId=M001  // Filter by member
?bookId=book001  // Filter by book

Response (200 OK):

[
  {
    "id": "T001",
    "memberId": "M001",
    "bookId": "book001",
    "borrowDate": "2024-01-15T10:00:00Z",
    "dueDate": "2024-02-15T10:00:00Z",
    "isReturned": false
  }
]

💻 cURL Example:

# Get all transactions
curl -X GET https://digital-library-api.vercel.app/api/transactions

# Filter by member
curl -X GET "https://digital-library-api.vercel.app/api/transactions?memberId=M001"

# Filter by book
curl -X GET "https://digital-library-api.vercel.app/api/transactions?bookId=book001"
GET/api/transactions/:id

Get a specific transaction by ID

Response (200 OK):

{
  "id": "T001",
  "memberId": "M001",
  "bookId": "book001",
  "borrowDate": "2024-01-15T10:00:00Z",
  "dueDate": "2024-02-15T10:00:00Z",
  "returnDate": null,
  "isReturned": false
}
POST/api/transactions

Create a new book borrowing transaction

Request Body:

{
  "id": "T009",
  "memberId": "M001",
  "bookId": "book002",
  "borrowDate": "2024-01-20T10:00:00Z",
  "dueDate": "2024-02-20T10:00:00Z"
}

Response (201 Created):

{
  "id": "T009",
  "memberId": "M001",
  "bookId": "book002",
  "borrowDate": "2024-01-20T10:00:00Z",
  "dueDate": "2024-02-20T10:00:00Z",
  "isReturned": false
}

💻 cURL Example:

curl -X POST https://digital-library-api.vercel.app/api/transactions \
  -H "Content-Type: application/json" \
  -d '{
    "id": "T009",
    "memberId": "M001",
    "bookId": "book002",
    "borrowDate": "2024-01-20T10:00:00Z",
    "dueDate": "2024-02-20T10:00:00Z"
  }'
PUT/api/transactions/:id

Update transaction (e.g., mark book as returned)

Request Body:

{
  "isReturned": true,
  "returnDate": "2024-02-10T15:30:00Z"
}
DELETE/api/transactions/:id

Delete a transaction record

Response (200 OK):

{
  "message": "Transaction deleted successfully"
}

⚠️Error Responses

400

Bad Request

{ "error": "Invalid request data" }
404

Not Found

{ "error": "Resource not found" }
409

Conflict

{ "error": "Resource already exists" }
500

Internal Server Error

{ "error": "Failed to process request" }