Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add API Documentation for Books, Borrowings, and Members with Pagination and Sorting #59

Merged
merged 5 commits into from
Oct 4, 2024
Merged

Add API Documentation for Books, Borrowings, and Members with Pagination and Sorting #59

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
80ba6ca
Update book-api.md
Guhapriya01 Oct 4, 2024
b194ef4
Update borrowings-api.md
Guhapriya01 Oct 4, 2024
4695566
Update books-api.md: Convert sortBy values to table format
Guhapriya01 Oct 4, 2024
897764b
docs: replace 'int' with 'Integer' for consistency
Guhapriya01 Oct 4, 2024
17f7940
Create members-api.md
Guhapriya01 Oct 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
174 changes: 149 additions & 25 deletions api-docs/book-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,45 +1,169 @@
# Library Management System API Documentation

<br/>

#### Base URL
### Base URL

```
http://localhost:8080/api
```

---

# Book API Endpoints

### Overview

The Book API provides a set of endpoints to manage the library's book collection. This includes functionalities to retrieve, add, update, and delete books. The API supports pagination, sorting, and detailed book information.

### 1. **Get All Books**

**Endpoint:** `/books`
**Method:** `GET`
**Description:** Retrieves a list of all books available in the library.
**Description:** Retrieves a paginated, sorted list of all books available in the library.

**Query Parameters:**

- `page` (Integer) : The page number of the result set (starting from 0). Default is `0`.
- `size` (Integer) : The number of books per page. Default is `5`.
- `sortBy` (String) : The field by which to sort the results (e.g., `title`, `author`, `publishedYear`). Default is `title`.
- `sortDir` (String) : The direction of sorting, either `asc` (ascending) or `desc` (descending). Default is `asc`.

**Example Requests:**

1. **Basic Request:**
```
GET /books
```
Retrieves the first 5 books sorted by `title` in ascending order.

2. **Pagination:**

Pagination allows the API to split the data into multiple pages. Use `page`
to specify the page number (starting from 0), and `size` to define how
many items are returned per page.

**Example:**

```
GET /books?page=0&size=7
```
Retrieves the first 7 books (on the first page).
```
GET /books?page=1&size=7
```

Retrieves the next 7 books (on the second page).

3. **Sorting:**

```
GET /books?sortBy=publishedYear&sortDir=desc
```

Retrieves books sorted by the `publishedYear` field in descending order.


```
GET /books?sortBy=author&sortDir=asc
```

Retrieves books sorted by the `author` field in ascending order.

**Supported Values for sortBy Query Parameter:**

| **Value** | **Description** |
|----------------------------|---------------------------------------------------|
| `bookId` | Unique identifier for the book. |
| `title` | Title of the book. |
| `author` | Author of the book. |
| `isbn` | ISBN number of the book. |
| `publisher` | Publisher of the book. |
| `publishedYear` | Year the book was published. |
| `genre` | Genre of the book. |
| `copiesAvailable` | Number of copies available of the book. |

4. **Pagination + Sorting:**
```
GET /books?page=1&size=5&sortBy=author&sortDir=asc
```

Retrieves the second page with 5 books, sorted by `author` in ascending order.

**Success Response:**
- **Code:** `200 OK`
- **Content:**
```json
[
{
"bookId": 1,
"title": "Book Title",
"author": "Author Name",
"isbn": "123-4567891234",
"publisher": "Publisher Name",
"publishedYear": 2021,
"genre": "Genre Name",
"copiesAvailable": 5
}

]
{
"content": [
{
"bookId": 11,
"title": "Circe",
"author": "Madeline Miller",
"isbn": "978-0316388681",
"publisher": "Little, Brown and Company",
"publishedYear": 2018,
"genre": "Fantasy",
"copiesAvailable": 7
},
{
"bookId": 10,
"title": "Educated",
"author": "Tara Westover",
"isbn": "978-0399590504",
"publisher": "Random House",
"publishedYear": 2018,
"genre": "Memoir",
"copiesAvailable": 5
},
{
"bookId": 12,
"title": "The Night Circus",
"author": "Erin Morgenstern",
"isbn": "978-0385534635",
"publisher": "Doubleday",
"publishedYear": 2011,
"genre": "Fantasy",
"copiesAvailable": 2
}
],
"pageable": {
"pageNumber": 0,
"pageSize": 5,
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"offset": 0,
"paged": true,
"unpaged": false
},
"last": false,
"totalPages": 1,
"totalElements": 3,
"first": true,
"numberOfElements": 3,
"size": 5,
"number": 0,
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"empty": false
}
```

**Error Responses:**
None

**Error Responses:**
- **Code:** `400 BAD REQUEST`
- **Message:** `The specified 'sortBy' value is invalid.`
- **Content:**
```json
{
"timestamp": "2024-10-03T07:37:08.364+00:00",
"message": "The specified 'sortBy' value is invalid.",
"details": "/api/books"
}
```

<br/>

---
Expand All @@ -53,7 +177,7 @@ None
**Description:** Retrieves the details of a book by its ID.

**Path Parameters:**
- `id` (int) : The unique identifier of the book.
- `id` (Integer) : The unique identifier of the book.

**Success Response:**
- **Code:** `200 OK`
Expand Down Expand Up @@ -140,7 +264,7 @@ None
**Description:** Updates the details of an existing book by its ID.

**Path Parameters:**
- `id` (int) : The unique identifier of the book.
- `id` (Integer) : The unique identifier of the book.

**Request Body:**
```json
Expand Down Expand Up @@ -196,7 +320,7 @@ None
**Description:** Deletes a book from the library by its ID.

**Path Parameters:**
- `id` (int) : The unique identifier of the book.
- `id` (Integer) : The unique identifier of the book.

**Success Response:**
- **Code:** `204 NO CONTENT`
Expand All @@ -218,4 +342,4 @@ None
<br/>
<br/>
<br/>
<br/>
<br/>
Loading
Loading