Skip to content

API

Run the server

The package also provides API functionality to interact with the recommendation model. To run the server, you need to run the run.py file:

python run.py

kitab.api.app

This module contains the API for the book recommendation system.

add_book(book)

Add a book to the database.

Parameters: book (dict): The book information.

Source code in kitab\api\app.py 
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
@app.post("/add_book")
def add_book(book: Book):
    """
    Add a book to the database.

    Parameters:
    book (dict): The book information.
    """
    # Get the book as a dictionary
    book = book.model_dump(exclude_unset=True)

    # Check if the book is in the database
    if get_book_by_ISBN(book["isbn"]) is not None:
        return {"message": "Book already exists. Use /update_book to update the book."}

    # If book isn't in the database, add it
    if add_book_db(book):
        return {"message": "Book added successfully"}

    return {"message": "Something went wrong. Book not added."}

add_log(description, recommendation_isbn, successful)

Add a log of a recommendation.

Parameters: description (str): The description of the book. recommendation_isbn (str): The ISBN of the recommended book. successful (bool): Whether the recommendation was successful.

Source code in kitab\api\app.py 
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
@app.post("/add_log")
def add_log(description: str, recommendation_isbn: str, successful: bool):
    """
    Add a log of a recommendation.

    Parameters:
    description (str): The description of the book.
    recommendation_isbn (str): The ISBN of the recommended book.
    successful (bool): Whether the recommendation was successful.
    """        
    # Check if the book is in the database
    if get_book_by_ISBN(recommendation_isbn) is None:
        return {"message": "No book with the given ISBN in the database."}

    # If book isn't in the database, add it
    if add_recommendation_log(description, recommendation_isbn, successful):
        return {"message": "Log successfully added."}

    return {"message": "Something went wrong. Log not added."}

get_book_isbn(isbn)

Get the book by ISBN.

Parameters: ISBN (str): The ISBN of the book.

Returns: dict: The book information.

Source code in kitab\api\app.py 
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
@app.get("/get_book_by_isbn")
def get_book_isbn(isbn: str):
    """
    Get the book by ISBN.

    Parameters:
    ISBN (str): The ISBN of the book.

    Returns:
    dict: The book information.
    """
    # Get the book by ISBN
    book = get_book_by_ISBN(isbn)

    # If it doesn't exist, return a message
    if book is None:
        return {"message": "Book not found."}

    return book

get_book_title(title)

Get the book by title.

Parameters: title (str): The title of the book.

Returns: dict: The book information.

Source code in kitab\api\app.py 
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
@app.get("/get_book_by_title")
def get_book_title(title: str):
    """
    Get the book by title.

    Parameters:
    title (str): The title of the book.

    Returns:
    dict: The book information.
    """
    # Get the book by ISBN
    book = get_book_by_title(title)

    # If it doesn't exist, return a message
    if book is None:
        return {"message": "Book not found."}

    return book

get_logs(recommendation_isbn)

Return the history of recommendations for the book with the given ISBN.

Parameters: recommendation_isbn (str): The ISBN of the book.

Returns: dict: The history of recommendations.

Source code in kitab\api\app.py 
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
@app.get("/get_logs")
def get_logs(recommendation_isbn: str):
    """
    Return the history of recommendations for the book with the given ISBN.

    Parameters:
    recommendation_isbn (str): The ISBN of the book.

    Returns:
    dict: The history of recommendations.
    """
    # Check if the book is in the database
    if get_book_by_ISBN(recommendation_isbn) is None:
        return {"message": "No book with the given ISBN in the database."}

    return get_history_by_recommendation_isbn(recommendation_isbn)

get_recommendations(description, n, get_available=True)

Return n book recommendations based on the description.

Parameters: description (str): The description of the book. n (int): The number of recommendations to return. get_available (bool, optional): Whether to only recommend available books. Defaults to True.

Returns: dict: The recommendations.

Source code in kitab\api\app.py 
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
@app.get("/get_recommendations")
def get_recommendations(description: str, n: int, get_available: bool = True):
    """
    Return n book recommendations based on the description.

    Parameters:
    description (str): The description of the book.
    n (int): The number of recommendations to return.
    get_available (bool, optional): Whether to only recommend available books. Defaults to True.

    Returns:
    dict: The recommendations.
    """
    # Get the recommendations
    books = recommend_books(description=description, n=n, get_available=get_available)

    return books

get_recommendations_by_isbn(isbn, n, get_available=True)

Return n book recommendations based on recommendation of the book with the given ISBN.

Parameters: ISBN (str): The ISBN of the book. n (int): The number of recommendations to return. get_available (bool, optional): Whether to only recommend available books. Defaults to True.

Returns: dict: The recommendations.

Source code in kitab\api\app.py 
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
@app.get("/get_recommendations_by_isbn")
def get_recommendations_by_isbn(isbn: str, n: int, get_available: bool = True):
    """
    Return n book recommendations based on recommendation of the book with the given ISBN.

    Parameters:
    ISBN (str): The ISBN of the book.
    n (int): The number of recommendations to return.
    get_available (bool, optional): Whether to only recommend available books. Defaults to True.

    Returns:
    dict: The recommendations.
    """
    # Check if the book exists in the database
    if get_book_by_ISBN(isbn) is None:
        return {"message": "Book does not exist. Please use /get_recommendations or /get_recommendations_by_title."}

    # Get the recommendations
    books = recommend_books_by_ISBN(ISBN=isbn, n=n, get_available=get_available)

    return books

get_recommendations_by_title(title, n, get_available=True)

Return n book recommendations based on recommendation of the book with the given title.

Parameters: title (str): The title of the book. n (int): The number of recommendations to return. get_available (bool, optional): Whether to only recommend available books. Defaults to True.

Returns: dict: The recommendations.

Source code in kitab\api\app.py 
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
@app.get("/get_recommendations_by_title")
def get_recommendations_by_title(title: str, n: int, get_available: bool = True):
    """
    Return n book recommendations based on recommendation of the book with the given title.

    Parameters:
    title (str): The title of the book.
    n (int): The number of recommendations to return.
    get_available (bool, optional): Whether to only recommend available books. Defaults to True.

    Returns:
    dict: The recommendations.
    """
    # Check if the book exists in the database
    if get_book_by_title(title) is None:
        return {"message": "Book does not exist. Please use /get_recommendations or /get_recommendations_by_isbn."}

    # Get the recommendations
    books = recommend_books_by_title(title=title, n=n, get_available=get_available)

    return books

run_api(port=5552)

Run the API server.

Examples:

>>> from kitab.utils import run_api
>>> run_api(port=5552)

Parameters: port (int): The port number on which the API server will run.

Returns: None

Source code in kitab\api\app.py 
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
def run_api(port=5552) -> None:
    """
    Run the API server.

    Examples:
        >>> from kitab.utils import run_api
        >>> run_api(port=5552)

    Parameters:
    port (int): The port number on which the API server will run.

    Returns:
    None
    """
    uvicorn.run(app, port=port)

update_book(isbn, new_book)

Update a book in the database.

Parameters: ISBNs (str): The ISBN of the book. new_book (dict): The new book information.

Source code in kitab\api\app.py 
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
@app.put("/update_book")
def update_book(isbn: str, new_book: BookUpdate):
    """
    Update a book in the database.

    Parameters:
    ISBNs (str): The ISBN of the book.
    new_book (dict): The new book information.
    """
    # If book isn't in the database, return a message
    if get_book_by_ISBN(isbn) is None:
        return {"message": "Book does not exist. Use /add_book to add the book."}

    # Get the set fields
    set_fields = new_book.model_dump(exclude_unset=True)

    # If no fields have been set, return a message
    if len(set_fields.keys()) == 0:
        return {"message": "Nothing passed."}

    # Compare the old book with the new one
    new_book = new_book.model_dump()
    old_book= get_book_by_ISBN(isbn)

    # Remove unchanged fields
    to_remove = []
    for field in new_book:
        if old_book[field] == new_book[field] or new_book[field] is None:
            to_remove.append(field)

    for field in to_remove:
        new_book.pop(field)

    # If no fields to be changed remained, return a message
    if len(new_book.keys()) == 0:
        return {"message": "Nothing new passed."}

    # Update the book
    if update_book_db(isbn, new_book):
        return {"message": "Book updated successfully"}

    return {"message": "Something went wrong. Book not updated."}