{ "version": "1.0", "modules": [ { "name": "User Management", "prefix": "/users", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create User", "description": "Creates a new user account with authentication credentials and personal information. Validates email uniqueness and password strength. Returns 409 if email already exists.", "request_body": { "schema_name": "UserCreate", "fields": [ { "name": "email", "type": "EmailStr", "required": true }, { "name": "first_name", "type": "str", "required": false }, { "name": "last_name", "type": "str", "required": false }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "ADMINISTRATOR", "LIBRARIAN", "MEMBER" ] }, { "name": "status", "type": "UserStatus", "required": true, "enum_values": [ "ACTIVE", "INACTIVE", "SUSPENDED" ] }, { "name": "password", "type": "str", "required": false } ] }, "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "str", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/{user_id}", "summary": "Get User By ID", "description": "Retrieves a single user by their unique identifier. Returns 404 if user not found.", "path_params": [ { "name": "user_id", "type": "str" } ], "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "str", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/", "summary": "List Users", "description": "Returns a paginated list of users. Supports optional filtering by role and status. Results are ordered by creation date descending.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "role", "type": "UserRole", "required": false }, { "name": "status", "type": "UserStatus", "required": false } ], "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "str", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/{user_id}", "summary": "Update User", "description": "Updates an existing user's information. Validates email uniqueness if changed and password strength if provided. Returns 404 if user not found, 409 if email conflict.", "path_params": [ { "name": "user_id", "type": "str" } ], "request_body": { "schema_name": "UserUpdate", "fields": [ { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "UserRole", "required": false, "nullable": true, "enum_values": [ "ADMINISTRATOR", "LIBRARIAN", "MEMBER" ] }, { "name": "status", "type": "UserStatus", "required": false, "nullable": true, "enum_values": [ "ACTIVE", "INACTIVE", "SUSPENDED" ] }, { "name": "password", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "str", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{user_id}", "summary": "Delete User", "description": "Deletes a user and all associated role records (administrator, librarian, or member) via cascade. Returns 404 if user not found.", "path_params": [ { "name": "user_id", "type": "str" } ], "status_code": 204 }, { "method": "POST", "path": "/administrators", "summary": "Create Administrator", "description": "Creates an administrator role record linked to an existing user. Validates that the user role is administrator and employee_id is unique. Returns 400 if user role mismatch, 404 if user not found, 409 if administrator record or employee_id already exists.", "request_body": { "schema_name": "AdministratorCreate", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "employee_id", "type": "str", "required": false, "nullable": true }, { "name": "hire_date", "type": "date", "required": false, "nullable": true } ] }, "response": { "schema_name": "AdministratorResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "employee_id", "type": "str", "required": false, "nullable": true }, { "name": "hire_date", "type": "date", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/administrators/{administrator_id}", "summary": "Get Administrator By ID", "description": "Retrieves a single administrator by their unique identifier. Returns 404 if administrator not found.", "path_params": [ { "name": "administrator_id", "type": "str" } ], "response": { "schema_name": "AdministratorResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "employee_id", "type": "str", "required": false, "nullable": true }, { "name": "hire_date", "type": "date", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/administrators/{administrator_id}/details", "summary": "Get Administrator Details", "description": "Retrieves an administrator with full user information eagerly loaded. Returns 404 if administrator not found.", "path_params": [ { "name": "administrator_id", "type": "str" } ], "response": { "schema_name": "AdministratorDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "employee_id", "type": "str", "required": false, "nullable": true }, { "name": "hire_date", "type": "date", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "user", "type": "UserDetailResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/administrators", "summary": "List Administrators", "description": "Returns a paginated list of administrators ordered by creation date descending.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 } ], "response": { "schema_name": "AdministratorResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "employee_id", "type": "str", "required": false, "nullable": true }, { "name": "hire_date", "type": "date", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/administrators/{administrator_id}", "summary": "Update Administrator", "description": "Updates an existing administrator record. Validates user_id role and employee_id uniqueness if changed. Returns 400 if user role mismatch, 404 if administrator or user not found, 409 if conflicts.", "path_params": [ { "name": "administrator_id", "type": "str" } ], "request_body": { "schema_name": "AdministratorUpdate", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "employee_id", "type": "str", "required": false, "nullable": true }, { "name": "hire_date", "type": "date", "required": false, "nullable": true } ] }, "response": { "schema_name": "AdministratorResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "employee_id", "type": "str", "required": false, "nullable": true }, { "name": "hire_date", "type": "date", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/administrators/{administrator_id}", "summary": "Delete Administrator", "description": "Deletes an administrator role record. The associated user record is not deleted. Returns 404 if administrator not found.", "path_params": [ { "name": "administrator_id", "type": "str" } ], "status_code": 204 }, { "method": "POST", "path": "/librarians", "summary": "Create Librarian", "description": "Creates a librarian role record linked to an existing user. Validates that the user role is librarian and employee_id is unique. Returns 400 if user role mismatch, 404 if user not found, 409 if librarian record or employee_id already exists.", "request_body": { "schema_name": "LibrarianCreate", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "employee_id", "type": "str", "required": false, "nullable": true }, { "name": "hire_date", "type": "date", "required": false, "nullable": true } ] }, "response": { "schema_name": "LibrarianResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "employee_id", "type": "str", "required": false, "nullable": true }, { "name": "hire_date", "type": "date", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/librarians/{librarian_id}", "summary": "Get Librarian By ID", "description": "Retrieves a single librarian by their unique identifier. Returns 404 if librarian not found.", "path_params": [ { "name": "librarian_id", "type": "str" } ], "response": { "schema_name": "LibrarianResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "employee_id", "type": "str", "required": false, "nullable": true }, { "name": "hire_date", "type": "date", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/librarians/{librarian_id}/details", "summary": "Get Librarian Details", "description": "Retrieves a librarian with full user information eagerly loaded. Returns 404 if librarian not found.", "path_params": [ { "name": "librarian_id", "type": "str" } ], "response": { "schema_name": "LibrarianDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "user", "type": "LibrarianUserResponse", "required": true, "fields": [ { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/librarians", "summary": "List Librarians", "description": "Returns a paginated list of librarians ordered by creation date descending.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 } ], "response": { "schema_name": "LibrarianResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "employee_id", "type": "str", "required": false, "nullable": true }, { "name": "hire_date", "type": "date", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/librarians/{librarian_id}", "summary": "Update Librarian", "description": "Updates an existing librarian record. Validates user_id role and employee_id uniqueness if changed. Returns 400 if user role mismatch, 404 if librarian or user not found, 409 if conflicts.", "path_params": [ { "name": "librarian_id", "type": "str" } ], "request_body": { "schema_name": "LibrarianUpdate", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "employee_id", "type": "str", "required": false, "nullable": true }, { "name": "hire_date", "type": "date", "required": false, "nullable": true } ] }, "response": { "schema_name": "LibrarianResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "employee_id", "type": "str", "required": false, "nullable": true }, { "name": "hire_date", "type": "date", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/librarians/{librarian_id}", "summary": "Delete Librarian", "description": "Deletes a librarian role record. The associated user record is not deleted. Returns 404 if librarian not found.", "path_params": [ { "name": "librarian_id", "type": "str" } ], "status_code": 204 }, { "method": "POST", "path": "/members", "summary": "Create Member", "description": "Creates a member role record linked to an existing user. Validates that the user role is member and membership_number is unique. Returns 400 if user role mismatch, 404 if user not found, 409 if member record or membership_number already exists.", "request_body": { "schema_name": "MemberCreate", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "membership_number", "type": "str", "required": false }, { "name": "membership_date", "type": "date", "required": true }, { "name": "membership_expiry", "type": "date", "required": false, "nullable": true }, { "name": "borrowing_limit", "type": "int", "required": false }, { "name": "account_standing", "type": "AccountStanding", "required": true, "enum_values": [ "GOOD", "WARNING", "SUSPENDED", "BLOCKED" ] } ] }, "response": { "schema_name": "MemberResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "membership_number", "type": "str", "required": true }, { "name": "membership_date", "type": "date", "required": true }, { "name": "membership_expiry", "type": "date", "required": false, "nullable": true }, { "name": "borrowing_limit", "type": "int", "required": true }, { "name": "account_standing", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/members/{member_id}", "summary": "Get Member By ID", "description": "Retrieves a single member by their unique identifier. Returns 404 if member not found.", "path_params": [ { "name": "member_id", "type": "str" } ], "response": { "schema_name": "MemberResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "membership_number", "type": "str", "required": true }, { "name": "membership_date", "type": "date", "required": true }, { "name": "membership_expiry", "type": "date", "required": false, "nullable": true }, { "name": "borrowing_limit", "type": "int", "required": true }, { "name": "account_standing", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/members/{member_id}/details", "summary": "Get Member Details", "description": "Retrieves a member with full user information eagerly loaded. Returns 404 if member not found.", "path_params": [ { "name": "member_id", "type": "str" } ], "response": { "schema_name": "MemberDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "membership_number", "type": "str", "required": true }, { "name": "user", "type": "MemberUserResponse", "required": true, "fields": [ { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/members", "summary": "List Members", "description": "Returns a paginated list of members. Supports optional filtering by account_standing. Results are ordered by creation date descending.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "account_standing", "type": "AccountStanding", "required": false } ], "response": { "schema_name": "MemberResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "membership_number", "type": "str", "required": true }, { "name": "membership_date", "type": "date", "required": true }, { "name": "membership_expiry", "type": "date", "required": false, "nullable": true }, { "name": "borrowing_limit", "type": "int", "required": true }, { "name": "account_standing", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/members/{member_id}", "summary": "Update Member", "description": "Updates an existing member record. Validates user_id role and membership_number uniqueness if changed. Returns 400 if user role mismatch, 404 if member or user not found, 409 if conflicts.", "path_params": [ { "name": "member_id", "type": "str" } ], "request_body": { "schema_name": "MemberUpdate", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "membership_number", "type": "str", "required": false, "nullable": true }, { "name": "membership_date", "type": "date", "required": false, "nullable": true }, { "name": "membership_expiry", "type": "date", "required": false, "nullable": true }, { "name": "borrowing_limit", "type": "int", "required": false, "nullable": true }, { "name": "account_standing", "type": "AccountStanding", "required": false, "nullable": true, "enum_values": [ "GOOD", "WARNING", "SUSPENDED", "BLOCKED" ] } ] }, "response": { "schema_name": "MemberResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "membership_number", "type": "str", "required": true }, { "name": "membership_date", "type": "date", "required": true }, { "name": "membership_expiry", "type": "date", "required": false, "nullable": true }, { "name": "borrowing_limit", "type": "int", "required": true }, { "name": "account_standing", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/members/{member_id}", "summary": "Delete Member", "description": "Deletes a member role record. The associated user record is not deleted. Returns 404 if member not found.", "path_params": [ { "name": "member_id", "type": "str" } ], "status_code": 204 } ] }, { "name": "", "prefix": "", "endpoints": [ { "method": "POST", "path": "/publishers", "summary": "Create Publisher", "description": "Creates a new publisher record with name and optional contact information. Returns 400 if email format is invalid.", "request_body": { "schema_name": "PublisherCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "str", "required": false, "nullable": true }, { "name": "website", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "PublisherResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "str", "required": false, "nullable": true }, { "name": "website", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/publishers/{publisher_id}", "summary": "Get Publisher By ID", "description": "Retrieves a single publisher by its unique identifier. Returns 404 if the publisher does not exist.", "path_params": [ { "name": "publisher_id", "type": "str" } ], "response": { "schema_name": "PublisherResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "str", "required": false, "nullable": true }, { "name": "website", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/publishers", "summary": "List Publishers", "description": "Returns a paginated list of publishers. Supports optional search filter on publisher name.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "PublisherResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "str", "required": false, "nullable": true }, { "name": "website", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/publishers/{publisher_id}", "summary": "Update Publisher", "description": "Updates an existing publisher record. Only provided fields are modified. Returns 404 if publisher not found, 400 if no fields provided.", "path_params": [ { "name": "publisher_id", "type": "str" } ], "request_body": { "schema_name": "PublisherUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "str", "required": false, "nullable": true }, { "name": "website", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "PublisherResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "str", "required": false, "nullable": true }, { "name": "website", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/publishers/{publisher_id}", "summary": "Delete Publisher", "description": "Deletes a publisher record. Returns 404 if the publisher does not exist.", "path_params": [ { "name": "publisher_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/authors", "summary": "Create Author", "description": "Creates a new author record with first name, last name, and optional biographical information.", "request_body": { "schema_name": "AuthorCreate", "fields": [ { "name": "first_name", "type": "str", "required": false }, { "name": "last_name", "type": "str", "required": false }, { "name": "biography", "type": "str", "required": false, "nullable": true }, { "name": "birth_date", "type": "date", "required": false, "nullable": true }, { "name": "nationality", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "AuthorResponse", "fields": [ { "name": "first_name", "type": "str", "required": false }, { "name": "last_name", "type": "str", "required": false }, { "name": "biography", "type": "str", "required": false, "nullable": true }, { "name": "birth_date", "type": "date", "required": false, "nullable": true }, { "name": "nationality", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/authors/{author_id}", "summary": "Get Author By ID", "description": "Retrieves a single author by its unique identifier. Returns 404 if the author does not exist.", "path_params": [ { "name": "author_id", "type": "str" } ], "response": { "schema_name": "AuthorResponse", "fields": [ { "name": "first_name", "type": "str", "required": false }, { "name": "last_name", "type": "str", "required": false }, { "name": "biography", "type": "str", "required": false, "nullable": true }, { "name": "birth_date", "type": "date", "required": false, "nullable": true }, { "name": "nationality", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/authors", "summary": "List Authors", "description": "Returns a paginated list of authors ordered by last name and first name. Supports optional search filter on first and last name.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "AuthorResponse", "fields": [ { "name": "first_name", "type": "str", "required": false }, { "name": "last_name", "type": "str", "required": false }, { "name": "biography", "type": "str", "required": false, "nullable": true }, { "name": "birth_date", "type": "date", "required": false, "nullable": true }, { "name": "nationality", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/authors/{author_id}", "summary": "Update Author", "description": "Updates an existing author record. Only provided fields are modified. Returns 404 if author not found, 400 if no fields provided.", "path_params": [ { "name": "author_id", "type": "str" } ], "request_body": { "schema_name": "AuthorUpdate", "fields": [ { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "biography", "type": "str", "required": false, "nullable": true }, { "name": "birth_date", "type": "date", "required": false, "nullable": true }, { "name": "nationality", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "AuthorResponse", "fields": [ { "name": "first_name", "type": "str", "required": false }, { "name": "last_name", "type": "str", "required": false }, { "name": "biography", "type": "str", "required": false, "nullable": true }, { "name": "birth_date", "type": "date", "required": false, "nullable": true }, { "name": "nationality", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/authors/{author_id}", "summary": "Delete Author", "description": "Deletes an author record. Returns 404 if the author does not exist.", "path_params": [ { "name": "author_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/categories", "summary": "Create Category", "description": "Creates a new category with a unique name and optional parent category for hierarchical structure. Returns 409 if category name already exists, 400 if parent category not found.", "request_body": { "schema_name": "CategoryCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "parent_category_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "CategoryResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "parent_category_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/categories/{category_id}", "summary": "Get Category By ID", "description": "Retrieves a single category by its unique identifier. Returns 404 if the category does not exist.", "path_params": [ { "name": "category_id", "type": "str" } ], "response": { "schema_name": "CategoryResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "parent_category_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/categories", "summary": "List Categories", "description": "Returns a paginated list of categories ordered by name. Supports optional search filter on category name.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "CategoryResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "parent_category_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/categories/{category_id}", "summary": "Update Category", "description": "Updates an existing category record. Only provided fields are modified. Returns 404 if category not found, 409 if new name conflicts, 400 if parent category invalid or circular reference.", "path_params": [ { "name": "category_id", "type": "str" } ], "request_body": { "schema_name": "CategoryUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "parent_category_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "CategoryResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "parent_category_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/categories/{category_id}", "summary": "Delete Category", "description": "Deletes a category record. Returns 404 if the category does not exist.", "path_params": [ { "name": "category_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/books", "summary": "Create Book", "description": "Creates a new book record with title, format, and inventory details. Validates ISBN uniqueness, publisher existence, and that available copies do not exceed total copies. Returns 409 if ISBN exists, 400 if validation fails.", "request_body": { "schema_name": "BookCreate", "fields": [ { "name": "isbn", "type": "str", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": false }, { "name": "subtitle", "type": "str", "required": false, "nullable": true }, { "name": "publisher_id", "type": "str", "required": false, "nullable": true }, { "name": "publication_date", "type": "date", "required": false, "nullable": true }, { "name": "edition", "type": "str", "required": false, "nullable": true }, { "name": "language", "type": "str", "required": false }, { "name": "pages", "type": "int", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "book_format", "type": "BookFormat", "required": true, "enum_values": [ "PHYSICAL", "DIGITAL" ] }, { "name": "total_copies", "type": "int", "required": false }, { "name": "available_copies", "type": "int", "required": false }, { "name": "location", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "BookStatus", "required": false, "enum_values": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "MAINTENANCE", "LOST", "DAMAGED" ] } ] }, "response": { "schema_name": "BookResponse", "fields": [ { "name": "isbn", "type": "str", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": false }, { "name": "subtitle", "type": "str", "required": false, "nullable": true }, { "name": "publisher_id", "type": "str", "required": false, "nullable": true }, { "name": "publication_date", "type": "date", "required": false, "nullable": true }, { "name": "edition", "type": "str", "required": false, "nullable": true }, { "name": "language", "type": "str", "required": false }, { "name": "pages", "type": "int", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "book_format", "type": "BookFormat", "required": true, "enum_values": [ "PHYSICAL", "DIGITAL" ] }, { "name": "total_copies", "type": "int", "required": false }, { "name": "available_copies", "type": "int", "required": false }, { "name": "location", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "BookStatus", "required": false, "enum_values": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "MAINTENANCE", "LOST", "DAMAGED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/books/{book_id}", "summary": "Get Book By ID", "description": "Retrieves a single book by its unique identifier. Returns 404 if the book does not exist.", "path_params": [ { "name": "book_id", "type": "str" } ], "response": { "schema_name": "BookResponse", "fields": [ { "name": "isbn", "type": "str", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": false }, { "name": "subtitle", "type": "str", "required": false, "nullable": true }, { "name": "publisher_id", "type": "str", "required": false, "nullable": true }, { "name": "publication_date", "type": "date", "required": false, "nullable": true }, { "name": "edition", "type": "str", "required": false, "nullable": true }, { "name": "language", "type": "str", "required": false }, { "name": "pages", "type": "int", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "book_format", "type": "BookFormat", "required": true, "enum_values": [ "PHYSICAL", "DIGITAL" ] }, { "name": "total_copies", "type": "int", "required": false }, { "name": "available_copies", "type": "int", "required": false }, { "name": "location", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "BookStatus", "required": false, "enum_values": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "MAINTENANCE", "LOST", "DAMAGED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/books", "summary": "List Books", "description": "Returns a paginated list of books ordered by title. Supports optional filters for search (title), status, and format.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "search", "type": "str", "required": false }, { "name": "status_filter", "type": "BookStatus", "required": false }, { "name": "book_format", "type": "BookFormat", "required": false } ], "response": { "schema_name": "BookResponse", "fields": [ { "name": "isbn", "type": "str", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": false }, { "name": "subtitle", "type": "str", "required": false, "nullable": true }, { "name": "publisher_id", "type": "str", "required": false, "nullable": true }, { "name": "publication_date", "type": "date", "required": false, "nullable": true }, { "name": "edition", "type": "str", "required": false, "nullable": true }, { "name": "language", "type": "str", "required": false }, { "name": "pages", "type": "int", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "book_format", "type": "BookFormat", "required": true, "enum_values": [ "PHYSICAL", "DIGITAL" ] }, { "name": "total_copies", "type": "int", "required": false }, { "name": "available_copies", "type": "int", "required": false }, { "name": "location", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "BookStatus", "required": false, "enum_values": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "MAINTENANCE", "LOST", "DAMAGED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/books/{book_id}", "summary": "Update Book", "description": "Updates an existing book record. Only provided fields are modified. Validates ISBN uniqueness, publisher existence, and available vs total copies. Returns 404 if book not found, 409 if ISBN conflict, 400 if validation fails.", "path_params": [ { "name": "book_id", "type": "str" } ], "request_body": { "schema_name": "BookUpdate", "fields": [ { "name": "isbn", "type": "str", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "subtitle", "type": "str", "required": false, "nullable": true }, { "name": "publisher_id", "type": "str", "required": false, "nullable": true }, { "name": "publication_date", "type": "date", "required": false, "nullable": true }, { "name": "edition", "type": "str", "required": false, "nullable": true }, { "name": "language", "type": "str", "required": false, "nullable": true }, { "name": "pages", "type": "int", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "book_format", "type": "BookFormat", "required": false, "nullable": true, "enum_values": [ "PHYSICAL", "DIGITAL" ] }, { "name": "total_copies", "type": "int", "required": false, "nullable": true }, { "name": "available_copies", "type": "int", "required": false, "nullable": true }, { "name": "location", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "BookStatus", "required": false, "nullable": true, "enum_values": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "MAINTENANCE", "LOST", "DAMAGED" ] } ] }, "response": { "schema_name": "BookResponse", "fields": [ { "name": "isbn", "type": "str", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": false }, { "name": "subtitle", "type": "str", "required": false, "nullable": true }, { "name": "publisher_id", "type": "str", "required": false, "nullable": true }, { "name": "publication_date", "type": "date", "required": false, "nullable": true }, { "name": "edition", "type": "str", "required": false, "nullable": true }, { "name": "language", "type": "str", "required": false }, { "name": "pages", "type": "int", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "book_format", "type": "BookFormat", "required": true, "enum_values": [ "PHYSICAL", "DIGITAL" ] }, { "name": "total_copies", "type": "int", "required": false }, { "name": "available_copies", "type": "int", "required": false }, { "name": "location", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "BookStatus", "required": false, "enum_values": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "MAINTENANCE", "LOST", "DAMAGED" ] }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/books/{book_id}", "summary": "Delete Book", "description": "Deletes a book record. Returns 404 if the book does not exist.", "path_params": [ { "name": "book_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/books/{book_id}/details", "summary": "Get Book Details", "description": "Retrieves a book with all related information including publisher, authors (ordered), and categories. Uses eager loading to prevent N+1 queries. Returns 404 if book not found.", "path_params": [ { "name": "book_id", "type": "str" } ], "response": { "schema_name": "BookDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "isbn", "type": "str", "required": false, "nullable": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/book-authors", "summary": "Create Book-Author Relationship", "description": "Links a book to an author with an ordering position for multi-author books. Validates that both book and author exist. Returns 409 if relationship already exists, 400 if book or author not found.", "request_body": { "schema_name": "BookauthorCreate", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "author_id", "type": "str", "required": true }, { "name": "author_order", "type": "int", "required": false } ] }, "response": { "schema_name": "BookauthorResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "author_id", "type": "str", "required": true }, { "name": "author_order", "type": "int", "required": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/book-authors/{bookauthor_id}", "summary": "Get Book-Author Relationship By ID", "description": "Retrieves a single book-author relationship by its unique identifier. Returns 404 if the relationship does not exist.", "path_params": [ { "name": "bookauthor_id", "type": "str" } ], "response": { "schema_name": "BookauthorResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "author_id", "type": "str", "required": true }, { "name": "author_order", "type": "int", "required": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/book-authors", "summary": "List Book-Author Relationships", "description": "Returns a paginated list of book-author relationships ordered by author order. Supports optional filter by book ID.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "book_id", "type": "str", "required": false } ], "response": { "schema_name": "BookauthorResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "author_id", "type": "str", "required": true }, { "name": "author_order", "type": "int", "required": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/book-authors/{bookauthor_id}", "summary": "Update Book-Author Relationship", "description": "Updates an existing book-author relationship. Only provided fields are modified. Validates book and author existence if changed. Returns 404 if relationship not found, 400 if validation fails.", "path_params": [ { "name": "bookauthor_id", "type": "str" } ], "request_body": { "schema_name": "BookauthorUpdate", "fields": [ { "name": "book_id", "type": "str", "required": false, "nullable": true }, { "name": "author_id", "type": "str", "required": false, "nullable": true }, { "name": "author_order", "type": "int", "required": false, "nullable": true } ] }, "response": { "schema_name": "BookauthorResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "author_id", "type": "str", "required": true }, { "name": "author_order", "type": "int", "required": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/book-authors/{bookauthor_id}", "summary": "Delete Book-Author Relationship", "description": "Deletes a book-author relationship. Returns 404 if the relationship does not exist.", "path_params": [ { "name": "bookauthor_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/book-categories", "summary": "Create Book-Category Relationship", "description": "Links a book to a category for classification. Validates that both book and category exist. Returns 409 if relationship already exists, 400 if book or category not found.", "request_body": { "schema_name": "BookcategoryCreate", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "category_id", "type": "str", "required": true } ] }, "response": { "schema_name": "BookcategoryResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "category_id", "type": "str", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/book-categories/{bookcategory_id}", "summary": "Get Book-Category Relationship By ID", "description": "Retrieves a single book-category relationship by its unique identifier. Returns 404 if the relationship does not exist.", "path_params": [ { "name": "bookcategory_id", "type": "str" } ], "response": { "schema_name": "BookcategoryResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "category_id", "type": "str", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/book-categories", "summary": "List Book-Category Relationships", "description": "Returns a paginated list of book-category relationships. Supports optional filter by book ID.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "book_id", "type": "str", "required": false } ], "response": { "schema_name": "BookcategoryResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "category_id", "type": "str", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/book-categories/{bookcategory_id}", "summary": "Update Book-Category Relationship", "description": "Updates an existing book-category relationship. Only provided fields are modified. Validates book and category existence if changed. Returns 404 if relationship not found, 400 if validation fails.", "path_params": [ { "name": "bookcategory_id", "type": "str" } ], "request_body": { "schema_name": "BookcategoryUpdate", "fields": [ { "name": "book_id", "type": "str", "required": false, "nullable": true }, { "name": "category_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "BookcategoryResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "category_id", "type": "str", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/book-categories/{bookcategory_id}", "summary": "Delete Book-Category Relationship", "description": "Deletes a book-category relationship. Returns 404 if the relationship does not exist.", "path_params": [ { "name": "bookcategory_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Circulation", "prefix": "/circulation", "endpoints": [ { "method": "POST", "path": "/loans", "summary": "Create Loan", "description": "Creates a new loan record for a member checking out a book. Validates member eligibility, borrowing limits, and book availability. Decrements available copies and updates book status if necessary. Returns 404 if book, member, or librarian not found. Returns 400 if book unavailable, member at borrowing limit, or member account suspended.", "request_body": { "schema_name": "LoanCreate", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "checkout_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "datetime", "required": true }, { "name": "return_date", "type": "datetime", "required": false, "nullable": true }, { "name": "renewal_count", "type": "int", "required": false, "default": 0 }, { "name": "status", "type": "LoanStatus", "required": true, "enum_values": [ "ACTIVE", "RETURNED", "OVERDUE", "LOST" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "LoanResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "checkout_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "datetime", "required": true }, { "name": "return_date", "type": "datetime", "required": false, "nullable": true }, { "name": "renewal_count", "type": "int", "required": false, "default": 0 }, { "name": "status", "type": "LoanStatus", "required": true, "enum_values": [ "ACTIVE", "RETURNED", "OVERDUE", "LOST" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/loans/{loan_id}", "summary": "Get Loan", "description": "Retrieves a single loan record by ID. Returns 404 if loan not found.", "path_params": [ { "name": "loan_id", "type": "str" } ], "response": { "schema_name": "LoanResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "checkout_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "datetime", "required": true }, { "name": "return_date", "type": "datetime", "required": false, "nullable": true }, { "name": "renewal_count", "type": "int", "required": false, "default": 0 }, { "name": "status", "type": "LoanStatus", "required": true, "enum_values": [ "ACTIVE", "RETURNED", "OVERDUE", "LOST" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/loans", "summary": "List Loans", "description": "Returns a paginated list of loans. Supports optional filters for book_id, member_id, and status. Results are ordered by creation date descending.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "book_id", "type": "str", "required": false }, { "name": "member_id", "type": "str", "required": false }, { "name": "loan_status", "type": "LoanStatus", "required": false } ], "response": { "schema_name": "LoanResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "checkout_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "datetime", "required": true }, { "name": "return_date", "type": "datetime", "required": false, "nullable": true }, { "name": "renewal_count", "type": "int", "required": false, "default": 0 }, { "name": "status", "type": "LoanStatus", "required": true, "enum_values": [ "ACTIVE", "RETURNED", "OVERDUE", "LOST" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PATCH", "path": "/loans/{loan_id}", "summary": "Update Loan", "description": "Updates an existing loan record. Only provided fields are updated. Validates foreign key references if book_id, member_id, or librarian_id are changed. Returns 404 if loan or referenced entities not found.", "path_params": [ { "name": "loan_id", "type": "str" } ], "request_body": { "schema_name": "LoanUpdate", "fields": [ { "name": "book_id", "type": "str", "required": false, "nullable": true }, { "name": "member_id", "type": "str", "required": false, "nullable": true }, { "name": "librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "checkout_date", "type": "datetime", "required": false, "nullable": true }, { "name": "due_date", "type": "datetime", "required": false, "nullable": true }, { "name": "return_date", "type": "datetime", "required": false, "nullable": true }, { "name": "renewal_count", "type": "int", "required": false, "nullable": true }, { "name": "status", "type": "LoanStatus", "required": false, "nullable": true, "enum_values": [ "ACTIVE", "RETURNED", "OVERDUE", "LOST" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "LoanResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "checkout_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "datetime", "required": true }, { "name": "return_date", "type": "datetime", "required": false, "nullable": true }, { "name": "renewal_count", "type": "int", "required": false, "default": 0 }, { "name": "status", "type": "LoanStatus", "required": true, "enum_values": [ "ACTIVE", "RETURNED", "OVERDUE", "LOST" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/loans/{loan_id}", "summary": "Delete Loan", "description": "Deletes a loan record by ID. Returns 404 if loan not found.", "path_params": [ { "name": "loan_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/loans/{loan_id}/details", "summary": "Get Loan Details", "description": "Retrieves a loan with full details including book information with publisher and authors, member user details, and librarian user details. Uses eager loading to prevent N+1 queries. Returns 404 if loan not found.", "path_params": [ { "name": "loan_id", "type": "str" } ], "response": { "schema_name": "LoanDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "book_id", "type": "str", "required": true }, { "name": "book", "type": "BookDetailResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "isbn", "type": "str", "required": false, "nullable": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/reservations", "summary": "Create Reservation", "description": "Creates a new reservation for a book that is currently unavailable. Validates member eligibility and reservation limits. Returns 404 if book or member not found. Returns 400 if book is available, member at reservation limit, or member account suspended.", "request_body": { "schema_name": "ReservationCreate", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "reservation_date", "type": "datetime", "required": true }, { "name": "expiry_date", "type": "datetime", "required": false, "nullable": true }, { "name": "queue_position", "type": "int", "required": true }, { "name": "status", "type": "ReservationStatus", "required": true, "enum_values": [ "PENDING", "READY", "FULFILLED", "CANCELLED", "EXPIRED" ] }, { "name": "notified_date", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "ReservationResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "reservation_date", "type": "datetime", "required": true }, { "name": "expiry_date", "type": "datetime", "required": false, "nullable": true }, { "name": "queue_position", "type": "int", "required": true }, { "name": "status", "type": "ReservationStatus", "required": true, "enum_values": [ "PENDING", "READY", "FULFILLED", "CANCELLED", "EXPIRED" ] }, { "name": "notified_date", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/reservations/{reservation_id}", "summary": "Get Reservation", "description": "Retrieves a single reservation record by ID. Returns 404 if reservation not found.", "path_params": [ { "name": "reservation_id", "type": "str" } ], "response": { "schema_name": "ReservationResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "reservation_date", "type": "datetime", "required": true }, { "name": "expiry_date", "type": "datetime", "required": false, "nullable": true }, { "name": "queue_position", "type": "int", "required": true }, { "name": "status", "type": "ReservationStatus", "required": true, "enum_values": [ "PENDING", "READY", "FULFILLED", "CANCELLED", "EXPIRED" ] }, { "name": "notified_date", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/reservations", "summary": "List Reservations", "description": "Returns a paginated list of reservations. Supports optional filters for book_id, member_id, and status. Results are ordered by creation date descending.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "book_id", "type": "str", "required": false }, { "name": "member_id", "type": "str", "required": false }, { "name": "reservation_status", "type": "ReservationStatus", "required": false } ], "response": { "schema_name": "ReservationResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "reservation_date", "type": "datetime", "required": true }, { "name": "expiry_date", "type": "datetime", "required": false, "nullable": true }, { "name": "queue_position", "type": "int", "required": true }, { "name": "status", "type": "ReservationStatus", "required": true, "enum_values": [ "PENDING", "READY", "FULFILLED", "CANCELLED", "EXPIRED" ] }, { "name": "notified_date", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PATCH", "path": "/reservations/{reservation_id}", "summary": "Update Reservation", "description": "Updates an existing reservation record. Only provided fields are updated. Validates foreign key references if book_id or member_id are changed. Returns 404 if reservation or referenced entities not found.", "path_params": [ { "name": "reservation_id", "type": "str" } ], "request_body": { "schema_name": "ReservationUpdate", "fields": [ { "name": "book_id", "type": "str", "required": false, "nullable": true }, { "name": "member_id", "type": "str", "required": false, "nullable": true }, { "name": "reservation_date", "type": "datetime", "required": false, "nullable": true }, { "name": "expiry_date", "type": "datetime", "required": false, "nullable": true }, { "name": "queue_position", "type": "int", "required": false, "nullable": true }, { "name": "status", "type": "ReservationStatus", "required": false, "nullable": true, "enum_values": [ "PENDING", "READY", "FULFILLED", "CANCELLED", "EXPIRED" ] }, { "name": "notified_date", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "ReservationResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "reservation_date", "type": "datetime", "required": true }, { "name": "expiry_date", "type": "datetime", "required": false, "nullable": true }, { "name": "queue_position", "type": "int", "required": true }, { "name": "status", "type": "ReservationStatus", "required": true, "enum_values": [ "PENDING", "READY", "FULFILLED", "CANCELLED", "EXPIRED" ] }, { "name": "notified_date", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/reservations/{reservation_id}", "summary": "Delete Reservation", "description": "Deletes a reservation record by ID. Returns 404 if reservation not found.", "path_params": [ { "name": "reservation_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/reservations/{reservation_id}/details", "summary": "Get Reservation Details", "description": "Retrieves a reservation with full details including book information with publisher and authors, and member user details. Uses eager loading to prevent N+1 queries. Returns 404 if reservation not found.", "path_params": [ { "name": "reservation_id", "type": "str" } ], "response": { "schema_name": "ReservationDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "book", "type": "BookDetail", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "isbn", "type": "str", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": true }, { "name": "publisher", "type": "PublisherDetail", "required": false, "nullable": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true } ] }, { "name": "book_authors", "type": "List[BookAuthorDetail]", "required": false, "is_list": true, "item_fields": [ { "name": "author", "type": "AuthorDetail", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] } ] }, { "name": "book_categories", "type": "List[BookCategoryDetail]", "required": false, "is_list": true, "item_fields": [ { "name": "category", "type": "CategoryDetail", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true } ] } ] } ] }, { "name": "member", "type": "MemberDetail", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user", "type": "UserDetail", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true } ] } ] }, { "name": "reservation_date", "type": "datetime", "required": true }, { "name": "expiry_date", "type": "datetime", "required": false, "nullable": true }, { "name": "queue_position", "type": "int", "required": true }, { "name": "status", "type": "ReservationStatus", "required": true, "enum_values": [ "PENDING", "READY", "FULFILLED", "CANCELLED", "EXPIRED" ] }, { "name": "notified_date", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/loans/{loan_id}/return", "summary": "Process Book Return", "description": "Processes the return of a borrowed book. Updates loan status to returned, increments book available copies, assesses overdue fines if applicable, and notifies the next member in the reservation queue if any. Returns 400 if loan already returned. Returns 404 if loan not found.", "path_params": [ { "name": "loan_id", "type": "str" } ], "response": { "schema_name": "LoanResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "checkout_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "datetime", "required": true }, { "name": "return_date", "type": "datetime", "required": false, "nullable": true }, { "name": "renewal_count", "type": "int", "required": false, "default": 0 }, { "name": "status", "type": "LoanStatus", "required": true, "enum_values": [ "ACTIVE", "RETURNED", "OVERDUE", "LOST" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/reservations/{reservation_id}/expire", "summary": "Process Reservation Expiry", "description": "Expires a reservation that was not picked up within the hold period. Updates reservation status to expired, notifies the next member in queue if any, and updates book status to available if no more reservations exist. Returns 400 if reservation is not in ready status. Returns 404 if reservation not found.", "path_params": [ { "name": "reservation_id", "type": "str" } ], "response": { "schema_name": "ReservationResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "reservation_date", "type": "datetime", "required": true }, { "name": "expiry_date", "type": "datetime", "required": false, "nullable": true }, { "name": "queue_position", "type": "int", "required": true }, { "name": "status", "type": "ReservationStatus", "required": true, "enum_values": [ "PENDING", "READY", "FULFILLED", "CANCELLED", "EXPIRED" ] }, { "name": "notified_date", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/loans/assess-overdue-fines", "summary": "Assess Overdue Fines", "description": "Batch job that identifies all overdue loans, calculates and creates fine records based on days overdue and rate, updates loan status to overdue, and suspends member accounts if total unpaid fines exceed threshold. Returns count of fines assessed.", "status_code": 200 }, { "method": "POST", "path": "/reservations/{reservation_id}/cancel", "summary": "Cancel Reservation", "description": "Cancels a reservation and updates queue positions for all subsequent reservations. If the cancelled reservation was ready, notifies the next member in queue. Returns 400 if reservation is already fulfilled, cancelled, or expired. Returns 404 if reservation not found.", "path_params": [ { "name": "reservation_id", "type": "str" } ], "response": { "schema_name": "ReservationResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "reservation_date", "type": "datetime", "required": true }, { "name": "expiry_date", "type": "datetime", "required": false, "nullable": true }, { "name": "queue_position", "type": "int", "required": true }, { "name": "status", "type": "ReservationStatus", "required": true, "enum_values": [ "PENDING", "READY", "FULFILLED", "CANCELLED", "EXPIRED" ] }, { "name": "notified_date", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/loans/{loan_id}/renew", "summary": "Renew Loan", "description": "Renews an active loan by extending the due date by 14 days. Validates that loan is active, not overdue, within renewal limit of 2, and has no pending reservations. Increments renewal count. Returns 400 if validation fails. Returns 404 if loan not found.", "path_params": [ { "name": "loan_id", "type": "str" } ], "response": { "schema_name": "LoanResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "checkout_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "datetime", "required": true }, { "name": "return_date", "type": "datetime", "required": false, "nullable": true }, { "name": "renewal_count", "type": "int", "required": false, "default": 0 }, { "name": "status", "type": "LoanStatus", "required": true, "enum_values": [ "ACTIVE", "RETURNED", "OVERDUE", "LOST" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 } ] }, { "name": "Fines", "prefix": "/fines", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Fine", "description": "Creates a new fine record for a member. Validates that the member exists and that amount_paid does not exceed the fine amount. Returns 404 if member or loan not found, 400 if validation fails.", "request_body": { "schema_name": "FineCreate", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "loan_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "amount_paid", "type": "Decimal", "required": false }, { "name": "reason", "type": "FineReason", "required": true, "enum_values": [ "OVERDUE", "DAMAGED", "LOST", "OTHER" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "FineStatus", "required": true, "enum_values": [ "UNPAID", "PARTIAL", "PAID", "WAIVED" ] }, { "name": "assessed_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "datetime", "required": false, "nullable": true }, { "name": "waived_by", "type": "str", "required": false, "nullable": true }, { "name": "waived_date", "type": "datetime", "required": false, "nullable": true }, { "name": "waived_reason", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "FineResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "loan_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "amount_paid", "type": "Decimal", "required": false }, { "name": "reason", "type": "FineReason", "required": true, "enum_values": [ "OVERDUE", "DAMAGED", "LOST", "OTHER" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "FineStatus", "required": true, "enum_values": [ "UNPAID", "PARTIAL", "PAID", "WAIVED" ] }, { "name": "assessed_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "datetime", "required": false, "nullable": true }, { "name": "waived_by", "type": "str", "required": false, "nullable": true }, { "name": "waived_date", "type": "datetime", "required": false, "nullable": true }, { "name": "waived_reason", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/{fine_id}", "summary": "Get Fine", "description": "Retrieves a single fine record by ID. Returns 404 if the fine does not exist.", "path_params": [ { "name": "fine_id", "type": "str" } ], "response": { "schema_name": "FineResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "loan_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "amount_paid", "type": "Decimal", "required": false }, { "name": "reason", "type": "FineReason", "required": true, "enum_values": [ "OVERDUE", "DAMAGED", "LOST", "OTHER" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "FineStatus", "required": true, "enum_values": [ "UNPAID", "PARTIAL", "PAID", "WAIVED" ] }, { "name": "assessed_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "datetime", "required": false, "nullable": true }, { "name": "waived_by", "type": "str", "required": false, "nullable": true }, { "name": "waived_date", "type": "datetime", "required": false, "nullable": true }, { "name": "waived_reason", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/", "summary": "List Fines", "description": "Returns a paginated list of fines. Supports optional filters for member_id and status. Results are ordered by assessed_date descending.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "member_id", "type": "str", "required": false }, { "name": "status", "type": "FineStatus", "required": false } ], "response": { "schema_name": "FineResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "loan_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "amount_paid", "type": "Decimal", "required": false }, { "name": "reason", "type": "FineReason", "required": true, "enum_values": [ "OVERDUE", "DAMAGED", "LOST", "OTHER" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "FineStatus", "required": true, "enum_values": [ "UNPAID", "PARTIAL", "PAID", "WAIVED" ] }, { "name": "assessed_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "datetime", "required": false, "nullable": true }, { "name": "waived_by", "type": "str", "required": false, "nullable": true }, { "name": "waived_date", "type": "datetime", "required": false, "nullable": true }, { "name": "waived_reason", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/{fine_id}", "summary": "Update Fine", "description": "Updates an existing fine record. Validates that amount_paid does not exceed amount. Returns 404 if fine not found, 400 if validation fails.", "path_params": [ { "name": "fine_id", "type": "str" } ], "request_body": { "schema_name": "FineUpdate", "fields": [ { "name": "member_id", "type": "str", "required": false, "nullable": true }, { "name": "loan_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "amount_paid", "type": "Decimal", "required": false, "nullable": true }, { "name": "reason", "type": "FineReason", "required": false, "nullable": true, "enum_values": [ "OVERDUE", "DAMAGED", "LOST", "OTHER" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "FineStatus", "required": false, "nullable": true, "enum_values": [ "UNPAID", "PARTIAL", "PAID", "WAIVED" ] }, { "name": "assessed_date", "type": "datetime", "required": false, "nullable": true }, { "name": "due_date", "type": "datetime", "required": false, "nullable": true }, { "name": "waived_by", "type": "str", "required": false, "nullable": true }, { "name": "waived_date", "type": "datetime", "required": false, "nullable": true }, { "name": "waived_reason", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "FineResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "loan_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "amount_paid", "type": "Decimal", "required": false }, { "name": "reason", "type": "FineReason", "required": true, "enum_values": [ "OVERDUE", "DAMAGED", "LOST", "OTHER" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "FineStatus", "required": true, "enum_values": [ "UNPAID", "PARTIAL", "PAID", "WAIVED" ] }, { "name": "assessed_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "datetime", "required": false, "nullable": true }, { "name": "waived_by", "type": "str", "required": false, "nullable": true }, { "name": "waived_date", "type": "datetime", "required": false, "nullable": true }, { "name": "waived_reason", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{fine_id}", "summary": "Delete Fine", "description": "Deletes a fine record by ID. Returns 404 if the fine does not exist.", "path_params": [ { "name": "fine_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/{fine_id}/details", "summary": "Get Fine Details", "description": "Retrieves a fine with all related data including member, loan, waived_by user, and payment history. Returns 404 if fine not found.", "path_params": [ { "name": "fine_id", "type": "str" } ], "response": { "schema_name": "FineDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "loan_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "amount_paid", "type": "Decimal", "required": true }, { "name": "reason", "type": "FineReason", "required": true, "enum_values": [ "OVERDUE", "DAMAGED", "LOST", "OTHER" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "FineStatus", "required": true, "enum_values": [ "UNPAID", "PARTIAL", "PAID", "WAIVED" ] }, { "name": "assessed_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "datetime", "required": false, "nullable": true }, { "name": "waived_by", "type": "str", "required": false, "nullable": true }, { "name": "waived_date", "type": "datetime", "required": false, "nullable": true }, { "name": "waived_reason", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "member", "type": "MemberDetailResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "membership_number", "type": "str", "required": true }, { "name": "user", "type": "MemberUserResponse", "required": true, "fields": [ { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true } ] } ] }, { "name": "loan", "type": "LoanDetailResponse", "required": false, "nullable": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "book_id", "type": "str", "required": true }, { "name": "book", "type": "BookDetailResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "isbn", "type": "str", "required": false, "nullable": true } ] } ] }, { "name": "waived_by_user", "type": "UserDetailResponse", "required": false, "nullable": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] }, { "name": "payments", "type": "List[PaymentDetailInFineResponse]", "required": false, "is_list": true, "item_fields": [ { "name": "id", "type": "str", "required": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "payment_date", "type": "datetime", "required": true }, { "name": "librarian", "type": "LibrarianDetailResponse", "required": false, "nullable": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "user", "type": "LibrarianUserResponse", "required": true, "fields": [ { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] } ] } ] } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{fine_id}/waive", "summary": "Waive Fine", "description": "Waives a fine by setting status to waived and recording who waived it and why. Returns 400 if fine is already waived or paid, 404 if fine or user not found.", "path_params": [ { "name": "fine_id", "type": "str" } ], "query_params": [ { "name": "waived_by", "type": "str", "required": false, "default": null }, { "name": "waived_reason", "type": "str", "required": false, "default": null } ], "response": { "schema_name": "FineResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "loan_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "amount_paid", "type": "Decimal", "required": false }, { "name": "reason", "type": "FineReason", "required": true, "enum_values": [ "OVERDUE", "DAMAGED", "LOST", "OTHER" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "FineStatus", "required": true, "enum_values": [ "UNPAID", "PARTIAL", "PAID", "WAIVED" ] }, { "name": "assessed_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "datetime", "required": false, "nullable": true }, { "name": "waived_by", "type": "str", "required": false, "nullable": true }, { "name": "waived_date", "type": "datetime", "required": false, "nullable": true }, { "name": "waived_reason", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 } ] }, { "name": "Engagement", "prefix": "/engagement", "endpoints": [ { "method": "POST", "path": "/reviews", "summary": "Create Review", "description": "Creates a new review for a book. Validates that the member has previously borrowed the book and has not already reviewed it. Returns 404 if book or member not found, 400 if member has not borrowed the book, and 409 if member has already reviewed the book.", "request_body": { "schema_name": "ReviewCreate", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "rating", "type": "int", "required": true }, { "name": "review_text", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "ReviewStatus", "required": true, "enum_values": [ "PUBLISHED", "PENDING", "HIDDEN", "FLAGGED" ] }, { "name": "review_date", "type": "datetime", "required": true } ] }, "response": { "schema_name": "ReviewResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "rating", "type": "int", "required": true }, { "name": "review_text", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "ReviewStatus", "required": true, "enum_values": [ "PUBLISHED", "PENDING", "HIDDEN", "FLAGGED" ] }, { "name": "review_date", "type": "datetime", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/reviews/{review_id}", "summary": "Get Review", "description": "Retrieves a single review by ID. Returns 404 if the review is not found.", "path_params": [ { "name": "review_id", "type": "str" } ], "response": { "schema_name": "ReviewResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "rating", "type": "int", "required": true }, { "name": "review_text", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "ReviewStatus", "required": true, "enum_values": [ "PUBLISHED", "PENDING", "HIDDEN", "FLAGGED" ] }, { "name": "review_date", "type": "datetime", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/reviews/{review_id}/details", "summary": "Get Review Details", "description": "Retrieves detailed review information including book title, ISBN, and member name. Returns 404 if the review is not found.", "path_params": [ { "name": "review_id", "type": "str" } ], "response": { "schema_name": "ReviewDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "book_id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "rating", "type": "int", "required": true }, { "name": "review_text", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "ReviewStatus", "required": true, "enum_values": [ "PUBLISHED", "PENDING", "HIDDEN", "FLAGGED" ] }, { "name": "review_date", "type": "datetime", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "book", "type": "BookInfo", "required": true, "fields": [ { "name": "title", "type": "str", "required": true }, { "name": "isbn", "type": "str", "required": false, "nullable": true } ] }, { "name": "member", "type": "MemberInfo", "required": true, "fields": [ { "name": "user", "type": "MemberUserInfo", "required": true, "fields": [ { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] } ] } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/reviews", "summary": "List Reviews", "description": "Returns a paginated list of reviews. Supports optional filters for book_id, member_id, and status.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "book_id", "type": "str", "required": false }, { "name": "member_id", "type": "str", "required": false }, { "name": "status", "type": "ReviewStatus", "required": false } ], "response": { "schema_name": "ReviewResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "rating", "type": "int", "required": true }, { "name": "review_text", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "ReviewStatus", "required": true, "enum_values": [ "PUBLISHED", "PENDING", "HIDDEN", "FLAGGED" ] }, { "name": "review_date", "type": "datetime", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PATCH", "path": "/reviews/{review_id}", "summary": "Update Review", "description": "Updates an existing review. Only provided fields are updated. Returns 404 if review, book, or member not found, and 400 if no fields are provided.", "path_params": [ { "name": "review_id", "type": "str" } ], "request_body": { "schema_name": "ReviewUpdate", "fields": [ { "name": "book_id", "type": "str", "required": false, "nullable": true }, { "name": "member_id", "type": "str", "required": false, "nullable": true }, { "name": "rating", "type": "int", "required": false, "nullable": true }, { "name": "review_text", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "ReviewStatus", "required": false, "nullable": true, "enum_values": [ "PUBLISHED", "PENDING", "HIDDEN", "FLAGGED" ] }, { "name": "review_date", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "ReviewResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "rating", "type": "int", "required": true }, { "name": "review_text", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "ReviewStatus", "required": true, "enum_values": [ "PUBLISHED", "PENDING", "HIDDEN", "FLAGGED" ] }, { "name": "review_date", "type": "datetime", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/reviews/{review_id}", "summary": "Delete Review", "description": "Deletes a review by ID. Returns 404 if the review is not found.", "path_params": [ { "name": "review_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/notifications", "summary": "Create Notification", "description": "Creates a new notification for a member. Returns 404 if the member is not found.", "request_body": { "schema_name": "NotificationCreate", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "notification_type", "type": "NotificationType", "required": true, "enum_values": [ "DUE_DATE", "OVERDUE", "RESERVATION_READY", "FINE_ASSESSED", "GENERAL", "ANNOUNCEMENT" ] }, { "name": "title", "type": "str", "required": true }, { "name": "message", "type": "str", "required": true }, { "name": "status", "type": "NotificationStatus", "required": true, "enum_values": [ "UNREAD", "READ", "ARCHIVED" ] }, { "name": "sent_date", "type": "datetime", "required": true }, { "name": "read_date", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "NotificationResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "notification_type", "type": "NotificationType", "required": true, "enum_values": [ "DUE_DATE", "OVERDUE", "RESERVATION_READY", "FINE_ASSESSED", "GENERAL", "ANNOUNCEMENT" ] }, { "name": "title", "type": "str", "required": true }, { "name": "message", "type": "str", "required": true }, { "name": "status", "type": "NotificationStatus", "required": true, "enum_values": [ "UNREAD", "READ", "ARCHIVED" ] }, { "name": "sent_date", "type": "datetime", "required": true }, { "name": "read_date", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/notifications/{notification_id}", "summary": "Get Notification", "description": "Retrieves a single notification by ID. Returns 404 if the notification is not found.", "path_params": [ { "name": "notification_id", "type": "str" } ], "response": { "schema_name": "NotificationResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "notification_type", "type": "NotificationType", "required": true, "enum_values": [ "DUE_DATE", "OVERDUE", "RESERVATION_READY", "FINE_ASSESSED", "GENERAL", "ANNOUNCEMENT" ] }, { "name": "title", "type": "str", "required": true }, { "name": "message", "type": "str", "required": true }, { "name": "status", "type": "NotificationStatus", "required": true, "enum_values": [ "UNREAD", "READ", "ARCHIVED" ] }, { "name": "sent_date", "type": "datetime", "required": true }, { "name": "read_date", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/notifications", "summary": "List Notifications", "description": "Returns a paginated list of notifications. Supports optional filters for member_id, notification_type, and status.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "member_id", "type": "str", "required": false }, { "name": "notification_type", "type": "NotificationType", "required": false }, { "name": "status", "type": "NotificationStatus", "required": false } ], "response": { "schema_name": "NotificationResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "notification_type", "type": "NotificationType", "required": true, "enum_values": [ "DUE_DATE", "OVERDUE", "RESERVATION_READY", "FINE_ASSESSED", "GENERAL", "ANNOUNCEMENT" ] }, { "name": "title", "type": "str", "required": true }, { "name": "message", "type": "str", "required": true }, { "name": "status", "type": "NotificationStatus", "required": true, "enum_values": [ "UNREAD", "READ", "ARCHIVED" ] }, { "name": "sent_date", "type": "datetime", "required": true }, { "name": "read_date", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PATCH", "path": "/notifications/{notification_id}", "summary": "Update Notification", "description": "Updates an existing notification. Only provided fields are updated. Returns 404 if notification or member not found, and 400 if no fields are provided.", "path_params": [ { "name": "notification_id", "type": "str" } ], "request_body": { "schema_name": "NotificationUpdate", "fields": [ { "name": "member_id", "type": "str", "required": false, "nullable": true }, { "name": "notification_type", "type": "NotificationType", "required": false, "nullable": true, "enum_values": [ "DUE_DATE", "OVERDUE", "RESERVATION_READY", "FINE_ASSESSED", "GENERAL", "ANNOUNCEMENT" ] }, { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "message", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "NotificationStatus", "required": false, "nullable": true, "enum_values": [ "UNREAD", "READ", "ARCHIVED" ] }, { "name": "sent_date", "type": "datetime", "required": false, "nullable": true }, { "name": "read_date", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "NotificationResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "notification_type", "type": "NotificationType", "required": true, "enum_values": [ "DUE_DATE", "OVERDUE", "RESERVATION_READY", "FINE_ASSESSED", "GENERAL", "ANNOUNCEMENT" ] }, { "name": "title", "type": "str", "required": true }, { "name": "message", "type": "str", "required": true }, { "name": "status", "type": "NotificationStatus", "required": true, "enum_values": [ "UNREAD", "READ", "ARCHIVED" ] }, { "name": "sent_date", "type": "datetime", "required": true }, { "name": "read_date", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/notifications/{notification_id}", "summary": "Delete Notification", "description": "Deletes a notification by ID. Returns 404 if the notification is not found.", "path_params": [ { "name": "notification_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/notifications/{notification_id}/mark-read", "summary": "Mark Notification as Read", "description": "Marks a notification as read and sets the read_date timestamp. Returns 404 if notification not found, and 400 if notification is already marked as read.", "path_params": [ { "name": "notification_id", "type": "str" } ], "response": { "schema_name": "NotificationResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "notification_type", "type": "NotificationType", "required": true, "enum_values": [ "DUE_DATE", "OVERDUE", "RESERVATION_READY", "FINE_ASSESSED", "GENERAL", "ANNOUNCEMENT" ] }, { "name": "title", "type": "str", "required": true }, { "name": "message", "type": "str", "required": true }, { "name": "status", "type": "NotificationStatus", "required": true, "enum_values": [ "UNREAD", "READ", "ARCHIVED" ] }, { "name": "sent_date", "type": "datetime", "required": true }, { "name": "read_date", "type": "datetime", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 } ] }, { "name": "Audit Logs", "prefix": "/audit-logs", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Audit Log", "description": "Creates a new audit log entry recording a system action. Validates that the user_id exists if provided. Returns the created audit log with generated ID and timestamps.", "request_body": { "schema_name": "AuditlogCreate", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action", "type": "str", "required": true }, { "name": "entity_type", "type": "str", "required": true }, { "name": "entity_id", "type": "str", "required": false, "nullable": true }, { "name": "old_values", "type": "dict", "required": false, "nullable": true }, { "name": "new_values", "type": "dict", "required": false, "nullable": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "user_agent", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true } ] }, "response": { "schema_name": "AuditlogResponse", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action", "type": "str", "required": true }, { "name": "entity_type", "type": "str", "required": true }, { "name": "entity_id", "type": "str", "required": false, "nullable": true }, { "name": "old_values", "type": "dict", "required": false, "nullable": true }, { "name": "new_values", "type": "dict", "required": false, "nullable": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "user_agent", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/{auditlog_id}", "summary": "Get Audit Log by ID", "description": "Retrieves a single audit log entry by its unique identifier. Returns 404 if the audit log does not exist.", "path_params": [ { "name": "auditlog_id", "type": "str" } ], "response": { "schema_name": "AuditlogResponse", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action", "type": "str", "required": true }, { "name": "entity_type", "type": "str", "required": true }, { "name": "entity_id", "type": "str", "required": false, "nullable": true }, { "name": "old_values", "type": "dict", "required": false, "nullable": true }, { "name": "new_values", "type": "dict", "required": false, "nullable": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "user_agent", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/", "summary": "List Audit Logs", "description": "Returns a paginated list of audit log entries ordered by timestamp descending. Supports optional filters for user_id, action, entity_type, and entity_id to narrow results.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "user_id", "type": "str", "required": false }, { "name": "action", "type": "str", "required": false }, { "name": "entity_type", "type": "str", "required": false }, { "name": "entity_id", "type": "str", "required": false } ], "response": { "schema_name": "AuditlogResponse", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action", "type": "str", "required": true }, { "name": "entity_type", "type": "str", "required": true }, { "name": "entity_id", "type": "str", "required": false, "nullable": true }, { "name": "old_values", "type": "dict", "required": false, "nullable": true }, { "name": "new_values", "type": "dict", "required": false, "nullable": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "user_agent", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/{auditlog_id}", "summary": "Update Audit Log", "description": "Updates an existing audit log entry. Only provided fields are modified; unset fields remain unchanged. Validates user_id if being updated. Returns 404 if the audit log does not exist.", "path_params": [ { "name": "auditlog_id", "type": "str" } ], "request_body": { "schema_name": "AuditlogUpdate", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action", "type": "str", "required": false, "nullable": true }, { "name": "entity_type", "type": "str", "required": false, "nullable": true }, { "name": "entity_id", "type": "str", "required": false, "nullable": true }, { "name": "old_values", "type": "dict", "required": false, "nullable": true }, { "name": "new_values", "type": "dict", "required": false, "nullable": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "user_agent", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "AuditlogResponse", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action", "type": "str", "required": true }, { "name": "entity_type", "type": "str", "required": true }, { "name": "entity_id", "type": "str", "required": false, "nullable": true }, { "name": "old_values", "type": "dict", "required": false, "nullable": true }, { "name": "new_values", "type": "dict", "required": false, "nullable": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "user_agent", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{auditlog_id}", "summary": "Delete Audit Log", "description": "Deletes an audit log entry by ID. Returns 404 if the audit log does not exist. Note: Business rules specify audit logs should not be deleted and must be retained for minimum 2 years.", "path_params": [ { "name": "auditlog_id", "type": "str" } ], "status_code": 200 } ] } ], "enums": { "UserRole": [ "ADMINISTRATOR", "LIBRARIAN", "MEMBER" ], "UserStatus": [ "ACTIVE", "INACTIVE", "SUSPENDED" ], "AccountStanding": [ "GOOD", "WARNING", "SUSPENDED", "BLOCKED" ], "BookFormat": [ "PHYSICAL", "DIGITAL" ], "BookStatus": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "MAINTENANCE", "LOST", "DAMAGED" ], "LoanStatus": [ "ACTIVE", "RETURNED", "OVERDUE", "LOST" ], "ReservationStatus": [ "PENDING", "READY", "FULFILLED", "CANCELLED", "EXPIRED" ], "FineReason": [ "OVERDUE", "DAMAGED", "LOST", "OTHER" ], "FineStatus": [ "UNPAID", "PARTIAL", "PAID", "WAIVED" ], "PaymentMethod": [ "CASH", "CREDIT_CARD", "DEBIT_CARD", "ONLINE", "CHECK", "OTHER" ], "ReviewStatus": [ "PUBLISHED", "PENDING", "HIDDEN", "FLAGGED" ], "NotificationType": [ "DUE_DATE", "OVERDUE", "RESERVATION_READY", "FINE_ASSESSED", "GENERAL", "ANNOUNCEMENT" ], "NotificationStatus": [ "UNREAD", "READ", "ARCHIVED" ] } }