API Reference – Book Endpoints
This section covers the Book resource for managing books in the demo RESTful API. It includes the full CRUD operations on individual books and listing all books. The Book endpoints are implemented in resources/book.py using Flask-RESTful’s Resource class and secured with JWT where noted. Under the hood, they delegate persistence to the BookModel ORM class in models/book.py.
Route Registration
The endpoints are registered in the application entrypoint:
api.add_resource(Book, '/book/<string:title>')
api.add_resource(BookList, '/books')
– app configuration in app.py
Index
- Data Model
- Retrieve Book Details
- Create a New Book
- Update or Create Book
- Delete a Book
- List All Books
Data Model
The BookModel defines the database schema and JSON representation for a book :
| Field | Type | Required | Description |
|---|---|---|---|
| id | Integer | Yes | Auto-incremented primary key |
| title | String (80) | Yes | Title of the book (unique) |
| author | String (80) | Yes | Author’s name |
| isbn | String (40) | Yes | ISBN identifier |
| release_date | String (10) | No | Release date (YYYY-MM-DD) |
| price | Float | Yes | Price of the book |
| store_id | Integer | Yes | Foreign key to stores.id |
class BookModel(db.Model):
__tablename__ = 'books'
id = db.Column(db.Integer, primary_key=True)
title = db.Column(db.String(80))
author = db.Column(db.String(80))
isbn = db.Column(db.String(40))
release_date = db.Column(db.String(10))
price = db.Column(db.Float(precision=2))
store_id = db.Column(db.Integer, db.ForeignKey('stores.id'))
store = db.relationship('StoreModel')
def json(self):
return {
'title': self.title,
'price': self.price,
'author': self.author,
'isbn': self.isbn,
'release_date': self.release_date
}
…
– BookModel in models/book.py
Retrieve Book Details
GET /book/{title}
Retrieves the details of a book by its title.
Authentication: JWT required
Decorator:@jwt_required()
{
"title": "Retrieve Book Details",
"description": "Fetch a book’s full details by title. Requires a valid JWT token.",
"method": "GET",
"baseUrl": "http://localhost:5000",
"endpoint": "/book/{title}",
"headers": [
{
"key": "Authorization",
"value": "JWT <token>",
"required": true
}
],
"pathParams": [
{
"key": "title",
"value": "Title of the book to retrieve",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"responses": {
"200": {
"description": "Book found",
"body": "{\n \"title\": \"Kalinga\",\n \"price\": 200.0,\n \"author\": \"sapan mohanty\",\n \"isbn\": \"WER3455\",\n \"release_date\": \"2020-12-12\"\n}"
},
"404": {
"description": "Book not found",
"body": "{\n \"message\": \"book not found\"\n}"
},
"401": {
"description": "Missing or invalid JWT",
"body": "{\n \"message\": \"Could not authorize.\"\n}"
}
}
}
Create a New Book
POST /book/{title}
Creates a new book record with the given title and JSON payload.
Validation:
price(float, required)store_id(int, required)author(string, required)isbn(string, required)release_date(string, optional)Error Cases:
- 400 if a book with the same title already exists
- 500 on database insertion error
{
"title": "Create a New Book",
"description": "Add a new book under the specified title.",
"method": "POST",
"baseUrl": "http://localhost:5000",
"endpoint": "/book/{title}",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"pathParams": [
{
"key": "title",
"value": "Unique title for the new book",
"required": true
}
],
"bodyType": "json",
"requestBody": "{\n \"price\": 29.99,\n \"store_id\": 2,\n \"author\": \"Jane Doe\",\n \"isbn\": \"1234567890\",\n \"release_date\": \"2021-08-15\"\n}",
"responses": {
"201": {
"description": "Book successfully created",
"body": "{\n \"title\": \"NewBook\",\n \"price\": 29.99,\n \"author\": \"Jane Doe\",\n \"isbn\": \"1234567890\",\n \"release_date\": \"2021-08-15\"\n}"
},
"400": {
"description": "Book with title already exists",
"body": "{\n \"message\": \"An book with title 'NewBook' already exists.\" \n}"
},
"500": {
"description": "Database insertion error",
"body": "{\n \"message\": \"An error occurred inserting the book.\" \n}"
}
}
}
Update or Create Book
PUT /book/{title}
Updates the price of an existing book or creates a new one if not found.
Payload: Same as POST (all required except
release_date)
{
"title": "Update or Create Book",
"description": "If the book exists, update its price; otherwise create it.",
"method": "PUT",
"baseUrl": "http://localhost:5000",
"endpoint": "/book/{title}",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"pathParams": [
{
"key": "title",
"value": "Title of the book to update or create",
"required": true
}
],
"bodyType": "json",
"requestBody": "{\n \"price\": 19.99,\n \"store_id\": 3,\n \"author\": \"John Smith\",\n \"isbn\": \"0987654321\",\n \"release_date\": \"2022-01-01\"\n}",
"responses": {
"200": {
"description": "Book created or updated",
"body": "{\n \"title\": \"MyBook\",\n \"price\": 19.99,\n \"author\": \"John Smith\",\n \"isbn\": \"0987654321\",\n \"release_date\": \"2022-01-01\"\n}"
}
}
}
Delete a Book
DELETE /book/{title}
Removes a book by title.
{
"title": "Delete a Book",
"description": "Delete the specified book if it exists.",
"method": "DELETE",
"baseUrl": "http://localhost:5000",
"endpoint": "/book/{title}",
"headers": [],
"pathParams": [
{
"key": "title",
"value": "Title of the book to delete",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"responses": {
"200": {
"description": "Book deleted successfully",
"body": "{\n \"message\": \"Item deleted.\" \n}"
},
"404": {
"description": "Book not found",
"body": "{\n \"message\": \"Item not found.\" \n}"
}
}
}
List All Books
GET /books
Retrieves a list of all books in the database. No authentication required.
{
"title": "List All Books",
"description": "Fetch all books. Public endpoint.",
"method": "GET",
"baseUrl": "http://localhost:5000",
"endpoint": "/books",
"headers": [],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"responses": {
"200": {
"description": "Array of book objects",
"body": "{\n \"books\": [\n {\n \"title\": \"Kalinga\",\n \"price\": 200.0,\n \"author\": \"sapan mohanty\",\n \"isbn\": \"WER3455\",\n \"release_date\": \"2020-12-12\"\n },\n …\n ]\n}"
}
}
}
Implementation Notes:
- Parsing & Validation
All create/update endpoints use a sharedreqparse.RequestParserto enforce required fields (price,store_id,author,isbn) and optionalrelease_date. - Authentication
Only the GET /book/{title} route is protected by JWT (@jwt_required()). - Persistence Layer
BookModel.find_by_title(),save_to_db(), anddelete_from_db()encapsulate database interactions with SQLAlchemy . - Error Handling
Consistent HTTP status codes:200 OKfor successful reads, updates, deletes201 Createdfor successful creation400 Bad Requestfor duplicate creation attempts404 Not Foundwhen a resource is missing500 Internal Server Erroron unexpected failures
This comprehensive reference provides everything you need to integrate, test, and extend the Book endpoints in your Flask RESTful API demo.