{ "version": "1.0", "modules": [ { "name": "Authentication", "prefix": "/auth", "endpoints": [ { "method": "POST", "path": "/users", "summary": "Create User", "description": "Creates a new user account with the specified role and credentials. Returns 409 if the email address already exists. Password must meet complexity requirements.", "request_body": { "schema_name": "UserCreate", "fields": [ { "name": "email", "type": "EmailStr", "required": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "GUEST", "MEMBER", "LIBRARIAN", "ADMINISTRATOR" ] }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "password", "type": "str", "required": 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 } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/users/{user_id}", "summary": "Get User By ID", "description": "Retrieves a single user by their unique identifier. Returns 404 if the user does not exist.", "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 } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/users", "summary": "List Users", "description": "Returns a paginated list of users. Supports optional filtering by role and active status.", "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": "is_active", "type": "bool", "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 } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/users/{user_id}", "summary": "Update User", "description": "Updates an existing user's information. Returns 404 if the user does not exist. Returns 409 if the new email address is already in use.", "path_params": [ { "name": "user_id", "type": "str" } ], "request_body": { "schema_name": "UserUpdate", "fields": [ { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "role", "type": "UserRole", "required": false, "nullable": true, "enum_values": [ "GUEST", "MEMBER", "LIBRARIAN", "ADMINISTRATOR" ] }, { "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": "is_active", "type": "bool", "required": false, "nullable": true }, { "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 } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/users/{user_id}", "summary": "Delete User", "description": "Deletes a user account and all associated role profiles. Returns 404 if the user does not exist.", "path_params": [ { "name": "user_id", "type": "str" } ], "status_code": 204 }, { "method": "POST", "path": "/members", "summary": "Create Member Profile", "description": "Creates a member profile for an existing user. Returns 404 if the user does not exist. Returns 409 if the user already has a member profile or the membership number is already in use.", "request_body": { "schema_name": "MemberCreate", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "membership_number", "type": "str", "required": true }, { "name": "join_date", "type": "date", "required": true }, { "name": "membership_status", "type": "MembershipStatus", "required": false, "enum_values": [ "ACTIVE", "SUSPENDED", "EXPIRED", "CANCELLED" ] }, { "name": "date_of_birth", "type": "date", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "library_branch_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "MemberResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "membership_number", "type": "str", "required": true }, { "name": "user", "type": "UserResponse", "required": true, "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 } ] } ], "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 the member does not exist.", "path_params": [ { "name": "member_id", "type": "str" } ], "response": { "schema_name": "MemberResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "membership_number", "type": "str", "required": true }, { "name": "user", "type": "UserResponse", "required": true, "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 } ] } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/members", "summary": "List Members", "description": "Returns a paginated list of members. Supports optional filtering by membership status and library branch.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "membership_status", "type": "MembershipStatus", "required": false }, { "name": "library_branch_id", "type": "str", "required": false } ], "response": { "schema_name": "MemberResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "membership_number", "type": "str", "required": true }, { "name": "user", "type": "UserResponse", "required": true, "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 } ] } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/members/{member_id}", "summary": "Update Member Profile", "description": "Updates an existing member's profile information. Returns 404 if the member does not exist. Returns 409 if the new membership number is already in use.", "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": "join_date", "type": "date", "required": false, "nullable": true }, { "name": "membership_status", "type": "MembershipStatus", "required": false, "nullable": true, "enum_values": [ "ACTIVE", "SUSPENDED", "EXPIRED", "CANCELLED" ] }, { "name": "date_of_birth", "type": "date", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "library_branch_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "MemberResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "membership_number", "type": "str", "required": true }, { "name": "user", "type": "UserResponse", "required": true, "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 } ] } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/members/{member_id}", "summary": "Delete Member Profile", "description": "Deletes a member profile. Returns 404 if the member does not exist. Returns 400 if the member has outstanding loans or fines.", "path_params": [ { "name": "member_id", "type": "str" } ], "status_code": 204 }, { "method": "GET", "path": "/members/{member_id}/details", "summary": "Get Member Details", "description": "Retrieves detailed member information including associated user account and library branch. Returns 404 if the member does not exist.", "path_params": [ { "name": "member_id", "type": "str" } ], "response": { "schema_name": "MemberDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "membership_number", "type": "str", "required": true }, { "name": "user", "type": "UserResponse", "required": true, "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": "library_branch", "type": "dict", "required": false, "nullable": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/librarians", "summary": "Create Librarian Profile", "description": "Creates a librarian profile for an existing user. Returns 404 if the user does not exist. Returns 409 if the user already has a librarian profile or the employee ID is already in use.", "request_body": { "schema_name": "LibrarianCreate", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "employee_id", "type": "str", "required": true }, { "name": "hire_date", "type": "date", "required": true }, { "name": "library_branch_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "LibrarianResponse", "fields": [ { "name": "employee_id", "type": "str", "required": true }, { "name": "hire_date", "type": "date", "required": true }, { "name": "library_branch_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "user_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": "/librarians/{librarian_id}", "summary": "Get Librarian By ID", "description": "Retrieves a single librarian by their unique identifier. Returns 404 if the librarian does not exist.", "path_params": [ { "name": "librarian_id", "type": "str" } ], "response": { "schema_name": "LibrarianResponse", "fields": [ { "name": "employee_id", "type": "str", "required": true }, { "name": "hire_date", "type": "date", "required": true }, { "name": "library_branch_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "user_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": "/librarians", "summary": "List Librarians", "description": "Returns a paginated list of librarians. Supports optional filtering by library branch.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "library_branch_id", "type": "str", "required": false } ], "response": { "schema_name": "LibrarianResponse", "fields": [ { "name": "employee_id", "type": "str", "required": true }, { "name": "hire_date", "type": "date", "required": true }, { "name": "library_branch_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "user_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": "/librarians/{librarian_id}", "summary": "Update Librarian Profile", "description": "Updates an existing librarian's profile information. Returns 404 if the librarian does not exist. Returns 409 if the new employee ID is already in use.", "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 }, { "name": "library_branch_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "LibrarianResponse", "fields": [ { "name": "employee_id", "type": "str", "required": true }, { "name": "hire_date", "type": "date", "required": true }, { "name": "library_branch_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "user_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": "/librarians/{librarian_id}", "summary": "Delete Librarian Profile", "description": "Deletes a librarian profile. Returns 404 if the librarian does not exist.", "path_params": [ { "name": "librarian_id", "type": "str" } ], "status_code": 204 }, { "method": "POST", "path": "/administrators", "summary": "Create Administrator Profile", "description": "Creates an administrator profile for an existing user. Returns 404 if the user does not exist. Returns 409 if the user already has an administrator profile.", "request_body": { "schema_name": "AdministratorCreate", "fields": [ { "name": "user_id", "type": "str", "required": true }, { "name": "admin_level", "type": "AdminLevel", "required": true, "enum_values": [ "SUPER", "STANDARD" ] } ] }, "response": { "schema_name": "AdministratorResponse", "fields": [ { "name": "admin_level", "type": "AdminLevel", "required": true, "enum_values": [ "SUPER", "STANDARD" ] }, { "name": "id", "type": "str", "required": true }, { "name": "user_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": "/administrators/{administrator_id}", "summary": "Get Administrator By ID", "description": "Retrieves a single administrator by their unique identifier. Returns 404 if the administrator does not exist.", "path_params": [ { "name": "administrator_id", "type": "str" } ], "response": { "schema_name": "AdministratorResponse", "fields": [ { "name": "admin_level", "type": "AdminLevel", "required": true, "enum_values": [ "SUPER", "STANDARD" ] }, { "name": "id", "type": "str", "required": true }, { "name": "user_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": "/administrators", "summary": "List Administrators", "description": "Returns a paginated list of administrators. Supports optional filtering by admin level.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "admin_level", "type": "AdminLevel", "required": false } ], "response": { "schema_name": "AdministratorResponse", "fields": [ { "name": "admin_level", "type": "AdminLevel", "required": true, "enum_values": [ "SUPER", "STANDARD" ] }, { "name": "id", "type": "str", "required": true }, { "name": "user_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": "/administrators/{administrator_id}", "summary": "Update Administrator Profile", "description": "Updates an existing administrator's profile information. Returns 404 if the administrator does not exist.", "path_params": [ { "name": "administrator_id", "type": "str" } ], "request_body": { "schema_name": "AdministratorUpdate", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "admin_level", "type": "AdminLevel", "required": false, "nullable": true, "enum_values": [ "SUPER", "STANDARD" ] } ] }, "response": { "schema_name": "AdministratorResponse", "fields": [ { "name": "admin_level", "type": "AdminLevel", "required": true, "enum_values": [ "SUPER", "STANDARD" ] }, { "name": "id", "type": "str", "required": true }, { "name": "user_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": "/administrators/{administrator_id}", "summary": "Delete Administrator Profile", "description": "Deletes an administrator profile. Returns 404 if the administrator does not exist.", "path_params": [ { "name": "administrator_id", "type": "str" } ], "status_code": 204 }, { "method": "POST", "path": "/register", "summary": "Register New Member", "description": "Registers a new member account with user credentials and member profile. Generates a unique membership number and creates both user and member records. Returns 409 if the email already exists.", "request_body": { "schema_name": "RegisterRequest", "fields": [ { "name": "email", "type": "EmailStr", "required": true }, { "name": "password", "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": "date_of_birth", "type": "date", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "LoginResponse", "fields": [ { "name": "user", "type": "UserResponse", "required": true, "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": "access_token", "type": "str", "required": true }, { "name": "token_type", "type": "str", "required": false, "default": "bearer" } ], "is_list": false }, "status_code": 201 }, { "method": "POST", "path": "/login", "summary": "User Login", "description": "Authenticates a user with email and password. Returns an access token on success. Returns 401 if credentials are invalid. Returns 403 if the account is inactive.", "request_body": { "schema_name": "LoginRequest", "fields": [ { "name": "email", "type": "EmailStr", "required": true }, { "name": "password", "type": "str", "required": true } ] }, "response": { "schema_name": "LoginResponse", "fields": [ { "name": "user", "type": "UserResponse", "required": true, "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": "access_token", "type": "str", "required": true }, { "name": "token_type", "type": "str", "required": false, "default": "bearer" } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/logout", "summary": "User Logout", "description": "Logs out the current user and invalidates their access token. Returns 404 if the user does not exist.", "status_code": 200 }, { "method": "POST", "path": "/forgot-password", "summary": "Request Password Reset", "description": "Initiates a password reset process by sending a reset link to the user's email address. Returns a success message regardless of whether the email exists for security reasons.", "request_body": { "schema_name": "ForgotPasswordRequest", "fields": [ { "name": "email", "type": "EmailStr", "required": true } ] }, "status_code": 200 }, { "method": "POST", "path": "/reset-password", "summary": "Reset Password", "description": "Resets a user's password using a valid reset token. The new password must meet complexity requirements. Returns 400 if the token is invalid or expired.", "request_body": { "schema_name": "ResetPasswordRequest", "fields": [ { "name": "token", "type": "str", "required": true }, { "name": "new_password", "type": "str", "required": true } ] }, "status_code": 200 } ] }, { "name": "Library Branches", "prefix": "/library-branches", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Library Branch", "description": "Creates a new library branch with contact information and operating hours. Validates email format if provided. Returns the created branch record with generated ID and timestamps.", "request_body": { "schema_name": "LibrarybranchCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "address", "type": "str", "required": false }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "str", "required": false, "nullable": true }, { "name": "operating_hours", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "LibrarybranchResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "address", "type": "str", "required": false }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "str", "required": false, "nullable": true }, { "name": "operating_hours", "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": "/", "summary": "List Library Branches", "description": "Returns a paginated list of library branches ordered by creation date descending. Supports optional search filter on branch name and address fields.", "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": "LibrarybranchResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "address", "type": "str", "required": false }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "str", "required": false, "nullable": true }, { "name": "operating_hours", "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": "GET", "path": "/{branch_id}", "summary": "Get Library Branch Details", "description": "Retrieves a single library branch by ID. Returns 404 if the branch does not exist.", "path_params": [ { "name": "branch_id", "type": "str" } ], "response": { "schema_name": "LibrarybranchResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "address", "type": "str", "required": false }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "str", "required": false, "nullable": true }, { "name": "operating_hours", "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": "PATCH", "path": "/{branch_id}", "summary": "Update Library Branch", "description": "Updates one or more fields of an existing library branch. Only provided fields are updated; unset fields remain unchanged. Validates email format if provided. Returns 404 if the branch does not exist.", "path_params": [ { "name": "branch_id", "type": "str" } ], "request_body": { "schema_name": "LibrarybranchUpdate", "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": "operating_hours", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "LibrarybranchResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "address", "type": "str", "required": false }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "str", "required": false, "nullable": true }, { "name": "operating_hours", "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": "/{branch_id}", "summary": "Delete Library Branch", "description": "Deletes a library branch by ID. Returns 404 if the branch does not exist. Returns 400 if the branch has associated members, librarians, or book copies due to foreign key constraints.", "path_params": [ { "name": "branch_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Catalog", "prefix": "/catalog", "endpoints": [ { "method": "POST", "path": "/authors", "summary": "Create Author", "description": "Creates a new author record with biographical information. Returns 400 if validation fails.", "request_body": { "schema_name": "AuthorCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "biography", "type": "str", "required": false, "nullable": true }, { "name": "birth_date", "type": "date", "required": false, "nullable": true }, { "name": "death_date", "type": "date", "required": false, "nullable": true }, { "name": "nationality", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "AuthorResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/authors/{author_id}", "summary": "Get Author", "description": "Retrieves a single author by ID. Returns 404 if the author does not exist.", "path_params": [ { "name": "author_id", "type": "str" } ], "response": { "schema_name": "AuthorResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/authors", "summary": "List Authors", "description": "Returns a paginated list of authors. Supports optional search filter on author 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": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "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 updated. Returns 404 if author not found.", "path_params": [ { "name": "author_id", "type": "str" } ], "request_body": { "schema_name": "AuthorUpdate", "fields": [ { "name": "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": "death_date", "type": "date", "required": false, "nullable": true }, { "name": "nationality", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "AuthorResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "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 author not found.", "path_params": [ { "name": "author_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/categories", "summary": "Create Category", "description": "Creates a new category for organizing books. Supports hierarchical categories via parent_category_id. Returns 409 if category name already exists.", "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", "description": "Retrieves a single category by ID. 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. 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 updated. Returns 404 if category not found, 409 if name conflicts.", "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 category not found.", "path_params": [ { "name": "category_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/books", "summary": "Create Book", "description": "Creates a new book record with metadata. Validates ISBN format if provided. Returns 409 if ISBN already exists.", "request_body": { "schema_name": "BookCreate", "fields": [ { "name": "isbn", "type": "str", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": false }, { "name": "publisher", "type": "str", "required": false, "nullable": true }, { "name": "publication_date", "type": "date", "required": false, "nullable": true }, { "name": "edition", "type": "str", "required": false, "nullable": true }, { "name": "number_of_pages", "type": "int", "required": false, "nullable": true }, { "name": "language", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "cover_image_url", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "BookResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "book_authors", "type": "list[BookAuthorResponse]", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/books/{book_id}", "summary": "Get Book", "description": "Retrieves a single book by ID. Returns 404 if the book does not exist.", "path_params": [ { "name": "book_id", "type": "str" } ], "response": { "schema_name": "BookResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "book_authors", "type": "list[BookAuthorResponse]", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/books", "summary": "List Books", "description": "Returns a paginated list of books. Supports optional search filter on book title.", "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": "BookResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "book_authors", "type": "list[BookAuthorResponse]", "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 updated. Returns 404 if book not found, 409 if ISBN conflicts.", "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": "publisher", "type": "str", "required": false, "nullable": true }, { "name": "publication_date", "type": "date", "required": false, "nullable": true }, { "name": "edition", "type": "str", "required": false, "nullable": true }, { "name": "number_of_pages", "type": "int", "required": false, "nullable": true }, { "name": "language", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "cover_image_url", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "BookResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "book_authors", "type": "list[BookAuthorResponse]", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/books/{book_id}", "summary": "Delete Book", "description": "Deletes a book record. Returns 400 if book has existing copies, 404 if book not found.", "path_params": [ { "name": "book_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/books/{book_id}/details", "summary": "Get Book Details", "description": "Retrieves comprehensive book information including authors, categories, and available copies. Returns 404 if book not found.", "path_params": [ { "name": "book_id", "type": "str" } ], "response": { "schema_name": "BookDetailsResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "isbn", "type": "str", "required": false, "nullable": true }, { "name": "title", "type": "str", "required": true }, { "name": "publisher", "type": "str", "required": false, "nullable": true }, { "name": "publication_date", "type": "date", "required": false, "nullable": true }, { "name": "edition", "type": "str", "required": false, "nullable": true }, { "name": "number_of_pages", "type": "int", "required": false, "nullable": true }, { "name": "language", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "cover_image_url", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "book_authors", "type": "List[BookAuthorDetailResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "author", "type": "AuthorDetailResponse", "required": true, "fields": [ { "name": "name", "type": "str", "required": true }, { "name": "biography", "type": "str", "required": false, "nullable": true } ] }, { "name": "author_order", "type": "int", "required": false, "nullable": true } ] }, { "name": "book_categories", "type": "List[BookCategoryDetailResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "category", "type": "CategoryDetailResponse", "required": true, "fields": [ { "name": "name", "type": "str", "required": true } ] } ] }, { "name": "book_copies", "type": "List[BookCopyDetailResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "barcode", "type": "str", "required": true }, { "name": "availability_status", "type": "AvailabilityStatus", "required": true, "enum_values": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "IN_TRANSIT", "MAINTENANCE", "LOST" ] }, { "name": "library_branch_id", "type": "str", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/books/search", "summary": "Search Books", "description": "Searches books by title, author name, ISBN, category, or language. Returns paginated results matching the search criteria.", "query_params": [ { "name": "title", "type": "str", "required": false }, { "name": "author", "type": "str", "required": false }, { "name": "isbn", "type": "str", "required": false }, { "name": "category", "type": "str", "required": false }, { "name": "language", "type": "str", "required": false }, { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 } ], "response": { "schema_name": "BookResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "book_authors", "type": "list[BookAuthorResponse]", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/books/{book_id}/availability", "summary": "Get Book Availability", "description": "Returns availability statistics for a book including total copies, available copies, and breakdown by library branch. Returns 404 if book not found.", "path_params": [ { "name": "book_id", "type": "str" } ], "response": { "schema_name": "BookAvailabilityResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "total_copies", "type": "int", "required": true }, { "name": "available_copies", "type": "int", "required": true }, { "name": "checked_out_copies", "type": "int", "required": true }, { "name": "reserved_copies", "type": "int", "required": true }, { "name": "copies_by_branch", "type": "List[dict]", "required": 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 optional ordering for multi-author books. Returns 404 if book or author not found, 409 if relationship already exists.", "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, "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, "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": "/book-authors/{bookauthor_id}", "summary": "Get Book-Author Relationship", "description": "Retrieves a single book-author relationship by ID. 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, "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": "/book-authors", "summary": "List Book-Author Relationships", "description": "Returns a paginated list of book-author 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": "BookauthorResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "author_id", "type": "str", "required": true }, { "name": "author_order", "type": "int", "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": "/book-authors/{bookauthor_id}", "summary": "Update Book-Author Relationship", "description": "Updates an existing book-author relationship. Only provided fields are updated. Returns 404 if relationship, book, or author not found.", "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, "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": "/book-authors/{bookauthor_id}", "summary": "Delete Book-Author Relationship", "description": "Deletes a book-author relationship. Returns 404 if relationship not found.", "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. Returns 404 if book or category not found, 409 if relationship already exists.", "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", "description": "Retrieves a single book-category relationship by ID. 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 updated. Returns 404 if relationship, book, or category not found.", "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 relationship not found.", "path_params": [ { "name": "bookcategory_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/book-copies", "summary": "Create Book Copy", "description": "Creates a new physical copy of a book with unique barcode and location. Returns 404 if book or branch not found, 409 if barcode already exists.", "request_body": { "schema_name": "BookcopyCreate", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "barcode", "type": "str", "required": false }, { "name": "library_branch_id", "type": "str", "required": true }, { "name": "condition_status", "type": "ConditionStatus", "required": true, "enum_values": [ "EXCELLENT", "GOOD", "FAIR", "POOR", "DAMAGED", "LOST" ] }, { "name": "availability_status", "type": "AvailabilityStatus", "required": true, "enum_values": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "IN_TRANSIT", "MAINTENANCE", "LOST" ] }, { "name": "acquisition_date", "type": "date", "required": false, "nullable": true }, { "name": "physical_location", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "BookcopyResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "barcode", "type": "str", "required": false }, { "name": "library_branch_id", "type": "str", "required": true }, { "name": "condition_status", "type": "ConditionStatus", "required": true, "enum_values": [ "EXCELLENT", "GOOD", "FAIR", "POOR", "DAMAGED", "LOST" ] }, { "name": "availability_status", "type": "AvailabilityStatus", "required": true, "enum_values": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "IN_TRANSIT", "MAINTENANCE", "LOST" ] }, { "name": "acquisition_date", "type": "date", "required": false, "nullable": true }, { "name": "physical_location", "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": "/book-copies/{bookcopy_id}", "summary": "Get Book Copy", "description": "Retrieves a single book copy by ID. Returns 404 if the book copy does not exist.", "path_params": [ { "name": "bookcopy_id", "type": "str" } ], "response": { "schema_name": "BookcopyResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "barcode", "type": "str", "required": false }, { "name": "library_branch_id", "type": "str", "required": true }, { "name": "condition_status", "type": "ConditionStatus", "required": true, "enum_values": [ "EXCELLENT", "GOOD", "FAIR", "POOR", "DAMAGED", "LOST" ] }, { "name": "availability_status", "type": "AvailabilityStatus", "required": true, "enum_values": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "IN_TRANSIT", "MAINTENANCE", "LOST" ] }, { "name": "acquisition_date", "type": "date", "required": false, "nullable": true }, { "name": "physical_location", "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": "/book-copies", "summary": "List Book Copies", "description": "Returns a paginated list of book copies. Supports optional filters by book_id, library_branch_id, and availability_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": "library_branch_id", "type": "str", "required": false }, { "name": "availability_status", "type": "AvailabilityStatus", "required": false } ], "response": { "schema_name": "BookcopyResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "barcode", "type": "str", "required": false }, { "name": "library_branch_id", "type": "str", "required": true }, { "name": "condition_status", "type": "ConditionStatus", "required": true, "enum_values": [ "EXCELLENT", "GOOD", "FAIR", "POOR", "DAMAGED", "LOST" ] }, { "name": "availability_status", "type": "AvailabilityStatus", "required": true, "enum_values": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "IN_TRANSIT", "MAINTENANCE", "LOST" ] }, { "name": "acquisition_date", "type": "date", "required": false, "nullable": true }, { "name": "physical_location", "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": "/book-copies/{bookcopy_id}", "summary": "Update Book Copy", "description": "Updates an existing book copy record. Only provided fields are updated. Returns 404 if copy, book, or branch not found, 409 if barcode conflicts.", "path_params": [ { "name": "bookcopy_id", "type": "str" } ], "request_body": { "schema_name": "BookcopyUpdate", "fields": [ { "name": "book_id", "type": "str", "required": false, "nullable": true }, { "name": "barcode", "type": "str", "required": false, "nullable": true }, { "name": "library_branch_id", "type": "str", "required": false, "nullable": true }, { "name": "condition_status", "type": "ConditionStatus", "required": false, "nullable": true, "enum_values": [ "EXCELLENT", "GOOD", "FAIR", "POOR", "DAMAGED", "LOST" ] }, { "name": "availability_status", "type": "AvailabilityStatus", "required": false, "nullable": true, "enum_values": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "IN_TRANSIT", "MAINTENANCE", "LOST" ] }, { "name": "acquisition_date", "type": "date", "required": false, "nullable": true }, { "name": "physical_location", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "BookcopyResponse", "fields": [ { "name": "book_id", "type": "str", "required": true }, { "name": "barcode", "type": "str", "required": false }, { "name": "library_branch_id", "type": "str", "required": true }, { "name": "condition_status", "type": "ConditionStatus", "required": true, "enum_values": [ "EXCELLENT", "GOOD", "FAIR", "POOR", "DAMAGED", "LOST" ] }, { "name": "availability_status", "type": "AvailabilityStatus", "required": true, "enum_values": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "IN_TRANSIT", "MAINTENANCE", "LOST" ] }, { "name": "acquisition_date", "type": "date", "required": false, "nullable": true }, { "name": "physical_location", "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": "/book-copies/{bookcopy_id}", "summary": "Delete Book Copy", "description": "Deletes a book copy record. Returns 404 if book copy not found.", "path_params": [ { "name": "bookcopy_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Circulation", "prefix": "/loans", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Loan", "description": "Creates a new loan record. Validates that the member and book copy exist, and that the librarian exists if provided. Returns 404 if any referenced entity is not found.", "request_body": { "schema_name": "LoanCreate", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "book_copy_id", "type": "str", "required": true }, { "name": "checkout_date", "type": "date", "required": true }, { "name": "due_date", "type": "date", "required": true }, { "name": "return_date", "type": "date", "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": "checked_out_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "checked_in_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "LoanResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "book_copy_id", "type": "str", "required": true }, { "name": "checkout_date", "type": "date", "required": true }, { "name": "due_date", "type": "date", "required": true }, { "name": "return_date", "type": "date", "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": "checked_out_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "checked_in_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "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": "/", "summary": "List Loans", "description": "Returns a paginated list of loans. Supports optional filters for member_id, book_copy_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": "member_id", "type": "str", "required": false }, { "name": "book_copy_id", "type": "str", "required": false }, { "name": "status", "type": "LoanStatus", "required": false } ], "response": { "schema_name": "LoanResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "book_copy_id", "type": "str", "required": true }, { "name": "checkout_date", "type": "date", "required": true }, { "name": "due_date", "type": "date", "required": true }, { "name": "return_date", "type": "date", "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": "checked_out_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "checked_in_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "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": "GET", "path": "/{loan_id}", "summary": "Get Loan", "description": "Returns a single loan by ID. Returns 404 if the loan does not exist.", "path_params": [ { "name": "loan_id", "type": "str" } ], "response": { "schema_name": "LoanResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "book_copy_id", "type": "str", "required": true }, { "name": "checkout_date", "type": "date", "required": true }, { "name": "due_date", "type": "date", "required": true }, { "name": "return_date", "type": "date", "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": "checked_out_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "checked_in_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "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": "PUT", "path": "/{loan_id}", "summary": "Update Loan", "description": "Updates an existing loan. Validates that any referenced entities (member, book copy, librarians) exist. Returns 404 if the loan or any referenced entity is not found.", "path_params": [ { "name": "loan_id", "type": "str" } ], "request_body": { "schema_name": "LoanUpdate", "fields": [ { "name": "member_id", "type": "str", "required": false, "nullable": true }, { "name": "book_copy_id", "type": "str", "required": false, "nullable": true }, { "name": "checkout_date", "type": "date", "required": false, "nullable": true }, { "name": "due_date", "type": "date", "required": false, "nullable": true }, { "name": "return_date", "type": "date", "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": "checked_out_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "checked_in_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "LoanResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "book_copy_id", "type": "str", "required": true }, { "name": "checkout_date", "type": "date", "required": true }, { "name": "due_date", "type": "date", "required": true }, { "name": "return_date", "type": "date", "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": "checked_out_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "checked_in_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "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": "/{loan_id}", "summary": "Delete Loan", "description": "Deletes a loan by ID. Returns 404 if the loan does not exist.", "path_params": [ { "name": "loan_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/{loan_id}/details", "summary": "Get Loan Details", "description": "Returns detailed loan information including member details with user information, book copy details with book and author information, and library branch information. All related data is eagerly loaded to avoid N+1 queries. Returns 404 if the loan does not exist.", "path_params": [ { "name": "loan_id", "type": "str" } ], "response": { "schema_name": "LoanDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "member", "type": "MemberResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "membership_number", "type": "str", "required": true }, { "name": "user", "type": "UserResponse", "required": true, "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": "book_copy", "type": "BookCopyResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "barcode", "type": "str", "required": true }, { "name": "book", "type": "BookResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "book_authors", "type": "list[BookAuthorResponse]", "required": true } ] }, { "name": "library_branch", "type": "LibraryBranchResponse", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "name", "type": "str", "required": true } ] } ] }, { "name": "checkout_date", "type": "date", "required": true }, { "name": "due_date", "type": "date", "required": true }, { "name": "return_date", "type": "date", "required": false, "nullable": true }, { "name": "renewal_count", "type": "int", "required": true }, { "name": "status", "type": "LoanStatus", "required": true, "enum_values": [ "ACTIVE", "RETURNED", "OVERDUE", "LOST" ] }, { "name": "checked_out_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "checked_in_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "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": "/checkout", "summary": "Checkout Book", "description": "Processes a book checkout for a member. Validates member eligibility (active status, under loan limit, outstanding fines under $10), book copy availability, and librarian if provided. Creates a loan with 14-day due date and updates book copy status to checked_out. Returns 400 if validation fails, 404 if any referenced entity is not found.", "request_body": { "schema_name": "CheckoutRequest", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "book_copy_id", "type": "str", "required": true }, { "name": "checked_out_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "LoanResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "book_copy_id", "type": "str", "required": true }, { "name": "checkout_date", "type": "date", "required": true }, { "name": "due_date", "type": "date", "required": true }, { "name": "return_date", "type": "date", "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": "checked_out_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "checked_in_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "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": "POST", "path": "/{loan_id}/return", "summary": "Return Book", "description": "Processes a book return. Updates loan status to returned, calculates and creates overdue fines if applicable (grace period of 1 day, $0.50 per day, max $10), checks for pending reservations and notifies next member if book is reserved, otherwise marks book copy as available. Returns 400 if loan is not active, 404 if loan or librarian is not found.", "path_params": [ { "name": "loan_id", "type": "str" } ], "request_body": { "schema_name": "ReturnRequest", "fields": [ { "name": "checked_in_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "LoanResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "book_copy_id", "type": "str", "required": true }, { "name": "checkout_date", "type": "date", "required": true }, { "name": "due_date", "type": "date", "required": true }, { "name": "return_date", "type": "date", "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": "checked_out_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "checked_in_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "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": "/{loan_id}/renew", "summary": "Renew Book", "description": "Renews a book loan by extending the due date by 14 days. Validates that the loan is active, not overdue, under renewal limit (2 renewals max), and the book is not reserved by another member. Returns 400 if validation fails, 404 if loan is not found.", "path_params": [ { "name": "loan_id", "type": "str" } ], "request_body": { "schema_name": "RenewRequest", "fields": [ { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "LoanResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "book_copy_id", "type": "str", "required": true }, { "name": "checkout_date", "type": "date", "required": true }, { "name": "due_date", "type": "date", "required": true }, { "name": "return_date", "type": "date", "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": "checked_out_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "checked_in_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "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": "Reservations", "prefix": "/reservations", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Reservation", "description": "Creates a new book reservation for a member. Validates that the member has active status, does not exceed the maximum of 3 concurrent active reservations, and does not already have a reservation for the same book. Assigns priority order based on existing pending reservations. Returns 404 if member or book not found, 400 if business rules are violated, 409 if duplicate reservation exists.", "request_body": { "schema_name": "ReservationCreate", "fields": [ { "name": "member_id", "type": "str", "required": false }, { "name": "book_id", "type": "str", "required": false }, { "name": "reservation_date", "type": "datetime", "required": true }, { "name": "expiration_date", "type": "datetime", "required": true }, { "name": "status", "type": "ReservationStatus", "required": false, "enum_values": [ "PENDING", "READY", "FULFILLED", "CANCELLED", "EXPIRED" ] }, { "name": "priority_order", "type": "int", "required": false, "nullable": true }, { "name": "notified_date", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "ReservationResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "book_id", "type": "str", "required": true }, { "name": "reservation_date", "type": "datetime", "required": true }, { "name": "expiration_date", "type": "datetime", "required": true }, { "name": "status", "type": "ReservationStatus", "required": true, "enum_values": [ "PENDING", "READY", "FULFILLED", "CANCELLED", "EXPIRED" ] }, { "name": "priority_order", "type": "int", "required": false, "nullable": true }, { "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": 201 }, { "method": "GET", "path": "/{reservation_id}", "summary": "Get Reservation", "description": "Retrieves a single reservation by ID. Returns 404 if the reservation does not exist.", "path_params": [ { "name": "reservation_id", "type": "str" } ], "response": { "schema_name": "ReservationResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "book_id", "type": "str", "required": true }, { "name": "reservation_date", "type": "datetime", "required": true }, { "name": "expiration_date", "type": "datetime", "required": true }, { "name": "status", "type": "ReservationStatus", "required": true, "enum_values": [ "PENDING", "READY", "FULFILLED", "CANCELLED", "EXPIRED" ] }, { "name": "priority_order", "type": "int", "required": false, "nullable": true }, { "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": "GET", "path": "/", "summary": "List Reservations", "description": "Returns a paginated list of reservations. Supports optional filters by member ID, book ID, and status. Results are ordered by reservation 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": "book_id", "type": "str", "required": false }, { "name": "status", "type": "ReservationStatus", "required": false } ], "response": { "schema_name": "ReservationResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "book_id", "type": "str", "required": true }, { "name": "reservation_date", "type": "datetime", "required": true }, { "name": "expiration_date", "type": "datetime", "required": true }, { "name": "status", "type": "ReservationStatus", "required": true, "enum_values": [ "PENDING", "READY", "FULFILLED", "CANCELLED", "EXPIRED" ] }, { "name": "priority_order", "type": "int", "required": false, "nullable": true }, { "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": true }, "status_code": 200 }, { "method": "PATCH", "path": "/{reservation_id}", "summary": "Update Reservation", "description": "Updates an existing reservation. Validates that any new member or book references exist. Only provided fields are updated. Returns 404 if reservation, member, or book not found.", "path_params": [ { "name": "reservation_id", "type": "str" } ], "request_body": { "schema_name": "ReservationUpdate", "fields": [ { "name": "member_id", "type": "str", "required": false, "nullable": true }, { "name": "book_id", "type": "str", "required": false, "nullable": true }, { "name": "reservation_date", "type": "datetime", "required": false, "nullable": true }, { "name": "expiration_date", "type": "datetime", "required": false, "nullable": true }, { "name": "status", "type": "ReservationStatus", "required": false, "nullable": true, "enum_values": [ "PENDING", "READY", "FULFILLED", "CANCELLED", "EXPIRED" ] }, { "name": "priority_order", "type": "int", "required": false, "nullable": true }, { "name": "notified_date", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "ReservationResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "book_id", "type": "str", "required": true }, { "name": "reservation_date", "type": "datetime", "required": true }, { "name": "expiration_date", "type": "datetime", "required": true }, { "name": "status", "type": "ReservationStatus", "required": true, "enum_values": [ "PENDING", "READY", "FULFILLED", "CANCELLED", "EXPIRED" ] }, { "name": "priority_order", "type": "int", "required": false, "nullable": true }, { "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": "DELETE", "path": "/{reservation_id}", "summary": "Delete Reservation", "description": "Deletes a reservation by ID. Returns 404 if the reservation does not exist.", "path_params": [ { "name": "reservation_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/{reservation_id}/details", "summary": "Get Reservation Details", "description": "Retrieves detailed reservation information including member details with user information and book details with author information. Uses eager loading to prevent N+1 queries. Returns 404 if the reservation does not exist.", "path_params": [ { "name": "reservation_id", "type": "str" } ], "response": { "schema_name": "ReservationDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "book_id", "type": "str", "required": true }, { "name": "reservation_date", "type": "datetime", "required": true }, { "name": "expiration_date", "type": "datetime", "required": true }, { "name": "status", "type": "ReservationStatus", "required": true, "enum_values": [ "PENDING", "READY", "FULFILLED", "CANCELLED", "EXPIRED" ] }, { "name": "priority_order", "type": "int", "required": false, "nullable": true }, { "name": "notified_date", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "member", "type": "MemberInfo", "required": true, "fields": [ { "name": "membership_number", "type": "str", "required": true }, { "name": "user", "type": "MemberUserInfo", "required": true, "fields": [ { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] } ] }, { "name": "book", "type": "BookInfo", "required": true, "fields": [ { "name": "title", "type": "str", "required": true }, { "name": "book_authors", "type": "list[BookAuthorDetail]", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{reservation_id}/cancel", "summary": "Cancel Reservation", "description": "Cancels a pending or ready reservation and updates the priority order for remaining pending reservations for the same book. Returns 400 if the reservation is not in pending or ready status, 404 if the reservation does not exist.", "path_params": [ { "name": "reservation_id", "type": "str" } ], "response": { "schema_name": "ReservationResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "member_id", "type": "str", "required": true }, { "name": "book_id", "type": "str", "required": true }, { "name": "reservation_date", "type": "datetime", "required": true }, { "name": "expiration_date", "type": "datetime", "required": true }, { "name": "status", "type": "ReservationStatus", "required": true, "enum_values": [ "PENDING", "READY", "FULFILLED", "CANCELLED", "EXPIRED" ] }, { "name": "priority_order", "type": "int", "required": false, "nullable": true }, { "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 } ] }, { "name": "Fines and Payments", "prefix": "/fines", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Fine", "description": "Creates a new fine record for a member. Validates that the member exists and the loan exists if provided. Returns 404 if member or loan not found.", "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": "reason", "type": "str", "required": true }, { "name": "issue_date", "type": "date", "required": true }, { "name": "payment_status", "type": "PaymentStatus", "required": true, "enum_values": [ "UNPAID", "PARTIALLY_PAID", "PAID", "WAIVED" ] }, { "name": "payment_date", "type": "date", "required": false, "nullable": true }, { "name": "amount_paid", "type": "Decimal", "required": false }, { "name": "waived_by_librarian_id", "type": "str", "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": "reason", "type": "str", "required": true }, { "name": "issue_date", "type": "date", "required": true }, { "name": "payment_status", "type": "PaymentStatus", "required": true, "enum_values": [ "UNPAID", "PARTIALLY_PAID", "PAID", "WAIVED" ] }, { "name": "payment_date", "type": "date", "required": false, "nullable": true }, { "name": "amount_paid", "type": "Decimal", "required": false }, { "name": "waived_by_librarian_id", "type": "str", "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": "/", "summary": "List Fines", "description": "Returns a paginated list of fines. Supports optional filtering by member_id and payment_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": "payment_status", "type": "PaymentStatus", "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": "reason", "type": "str", "required": true }, { "name": "issue_date", "type": "date", "required": true }, { "name": "payment_status", "type": "PaymentStatus", "required": true, "enum_values": [ "UNPAID", "PARTIALLY_PAID", "PAID", "WAIVED" ] }, { "name": "payment_date", "type": "date", "required": false, "nullable": true }, { "name": "amount_paid", "type": "Decimal", "required": false }, { "name": "waived_by_librarian_id", "type": "str", "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": "GET", "path": "/{fine_id}", "summary": "Get Fine", "description": "Returns a single fine 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": "reason", "type": "str", "required": true }, { "name": "issue_date", "type": "date", "required": true }, { "name": "payment_status", "type": "PaymentStatus", "required": true, "enum_values": [ "UNPAID", "PARTIALLY_PAID", "PAID", "WAIVED" ] }, { "name": "payment_date", "type": "date", "required": false, "nullable": true }, { "name": "amount_paid", "type": "Decimal", "required": false }, { "name": "waived_by_librarian_id", "type": "str", "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": "PUT", "path": "/{fine_id}", "summary": "Update Fine", "description": "Updates an existing fine. Validates that referenced member, loan, and librarian exist if being updated. Returns 404 if fine not found.", "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": "reason", "type": "str", "required": false, "nullable": true }, { "name": "issue_date", "type": "date", "required": false, "nullable": true }, { "name": "payment_status", "type": "PaymentStatus", "required": false, "nullable": true, "enum_values": [ "UNPAID", "PARTIALLY_PAID", "PAID", "WAIVED" ] }, { "name": "payment_date", "type": "date", "required": false, "nullable": true }, { "name": "amount_paid", "type": "Decimal", "required": false, "nullable": true }, { "name": "waived_by_librarian_id", "type": "str", "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": "reason", "type": "str", "required": true }, { "name": "issue_date", "type": "date", "required": true }, { "name": "payment_status", "type": "PaymentStatus", "required": true, "enum_values": [ "UNPAID", "PARTIALLY_PAID", "PAID", "WAIVED" ] }, { "name": "payment_date", "type": "date", "required": false, "nullable": true }, { "name": "amount_paid", "type": "Decimal", "required": false }, { "name": "waived_by_librarian_id", "type": "str", "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 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": "Returns detailed information about a fine including member details and associated loan and book information. 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": "reason", "type": "str", "required": true }, { "name": "issue_date", "type": "date", "required": true }, { "name": "payment_status", "type": "PaymentStatus", "required": true, "enum_values": [ "UNPAID", "PARTIALLY_PAID", "PAID", "WAIVED" ] }, { "name": "payment_date", "type": "date", "required": false, "nullable": true }, { "name": "amount_paid", "type": "Decimal", "required": true }, { "name": "waived_by_librarian_id", "type": "str", "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": "FineDetailMember", "required": true, "fields": [ { "name": "membership_number", "type": "str", "required": true }, { "name": "user", "type": "FineDetailMemberUser", "required": true, "fields": [ { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] } ] }, { "name": "loan", "type": "FineDetailLoan", "required": false, "nullable": true, "fields": [ { "name": "book_copy", "type": "FineDetailLoanBookCopy", "required": true, "fields": [ { "name": "book", "type": "FineDetailLoanBookCopyBook", "required": true, "fields": [ { "name": "title", "type": "str", "required": true } ] } ] } ] } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{fine_id}/waive", "summary": "Waive Fine", "description": "Waives a fine by marking it as waived and recording the librarian who waived it and the reason. Returns 400 if fine is already paid or waived, 404 if fine or librarian not found.", "path_params": [ { "name": "fine_id", "type": "str" } ], "query_params": [ { "name": "librarian_id", "type": "str", "required": false, "default": null }, { "name": "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": "reason", "type": "str", "required": true }, { "name": "issue_date", "type": "date", "required": true }, { "name": "payment_status", "type": "PaymentStatus", "required": true, "enum_values": [ "UNPAID", "PARTIALLY_PAID", "PAID", "WAIVED" ] }, { "name": "payment_date", "type": "date", "required": false, "nullable": true }, { "name": "amount_paid", "type": "Decimal", "required": false }, { "name": "waived_by_librarian_id", "type": "str", "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": "POST", "path": "/payments", "summary": "Create Payment", "description": "Creates a new payment record. Validates that the member exists and the fine exists if provided. Returns 404 if member or fine not found, 409 if reference number already exists.", "request_body": { "schema_name": "PaymentCreate", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "fine_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CASH", "CREDIT_CARD", "DEBIT_CARD", "ONLINE", "CHECK" ] }, { "name": "transaction_date", "type": "datetime", "required": true }, { "name": "reference_number", "type": "str", "required": false, "nullable": true }, { "name": "processed_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "PaymentResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "fine_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CASH", "CREDIT_CARD", "DEBIT_CARD", "ONLINE", "CHECK" ] }, { "name": "transaction_date", "type": "datetime", "required": true }, { "name": "reference_number", "type": "str", "required": false, "nullable": true }, { "name": "processed_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "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": "/payments", "summary": "List Payments", "description": "Returns a paginated list of payments. Supports optional filtering by member_id and fine_id.", "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": "fine_id", "type": "str", "required": false } ], "response": { "schema_name": "PaymentResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "fine_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CASH", "CREDIT_CARD", "DEBIT_CARD", "ONLINE", "CHECK" ] }, { "name": "transaction_date", "type": "datetime", "required": true }, { "name": "reference_number", "type": "str", "required": false, "nullable": true }, { "name": "processed_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "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": "GET", "path": "/payments/{payment_id}", "summary": "Get Payment", "description": "Returns a single payment by ID. Returns 404 if the payment does not exist.", "path_params": [ { "name": "payment_id", "type": "str" } ], "response": { "schema_name": "PaymentResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "fine_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CASH", "CREDIT_CARD", "DEBIT_CARD", "ONLINE", "CHECK" ] }, { "name": "transaction_date", "type": "datetime", "required": true }, { "name": "reference_number", "type": "str", "required": false, "nullable": true }, { "name": "processed_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "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": "PUT", "path": "/payments/{payment_id}", "summary": "Update Payment", "description": "Updates an existing payment. Validates that referenced member, fine, and librarian exist if being updated. Returns 404 if payment not found, 409 if reference number already exists.", "path_params": [ { "name": "payment_id", "type": "str" } ], "request_body": { "schema_name": "PaymentUpdate", "fields": [ { "name": "member_id", "type": "str", "required": false, "nullable": true }, { "name": "fine_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "payment_method", "type": "PaymentMethod", "required": false, "nullable": true, "enum_values": [ "CASH", "CREDIT_CARD", "DEBIT_CARD", "ONLINE", "CHECK" ] }, { "name": "transaction_date", "type": "datetime", "required": false, "nullable": true }, { "name": "reference_number", "type": "str", "required": false, "nullable": true }, { "name": "processed_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "PaymentResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "fine_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CASH", "CREDIT_CARD", "DEBIT_CARD", "ONLINE", "CHECK" ] }, { "name": "transaction_date", "type": "datetime", "required": true }, { "name": "reference_number", "type": "str", "required": false, "nullable": true }, { "name": "processed_by_librarian_id", "type": "str", "required": false, "nullable": true }, { "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": "/payments/{payment_id}", "summary": "Delete Payment", "description": "Deletes a payment by ID. Returns 404 if the payment does not exist.", "path_params": [ { "name": "payment_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/payments/process", "summary": "Process Payment", "description": "Processes a payment for a member by applying the payment amount to outstanding fines in order of issue date. Updates fine payment status and creates a payment record. Returns 400 if member has no outstanding fines, 404 if member or librarian not found, 409 if reference number already exists.", "query_params": [ { "name": "member_id", "type": "str", "required": false, "default": null }, { "name": "amount", "type": "Decimal", "required": false, "default": null }, { "name": "payment_method", "type": "PaymentMethod", "required": false, "default": null }, { "name": "processed_by_librarian_id", "type": "str", "required": false }, { "name": "reference_number", "type": "str", "required": false }, { "name": "notes", "type": "str", "required": false } ], "status_code": 200 } ] }, { "name": "System", "prefix": "/system", "endpoints": [ { "method": "POST", "path": "/audit-logs", "summary": "Create Audit Log", "description": "Creates a new audit log entry recording a system action. Captures user, action type, entity affected, timestamp, IP address, and additional details in JSON format.", "request_body": { "schema_name": "AuditlogCreate", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action_type", "type": "str", "required": false }, { "name": "entity_type", "type": "str", "required": false, "nullable": true }, { "name": "entity_id", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "details", "type": "dict", "required": false, "nullable": true } ] }, "response": { "schema_name": "AuditlogResponse", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action_type", "type": "str", "required": false }, { "name": "entity_type", "type": "str", "required": false, "nullable": true }, { "name": "entity_id", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "details", "type": "dict", "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": "/audit-logs/{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", "type": "str", "required": false }, { "name": "entity_type", "type": "str", "required": false, "nullable": true }, { "name": "entity_id", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "details", "type": "dict", "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": "/audit-logs", "summary": "List Audit Logs", "description": "Returns a paginated list of audit log entries ordered by timestamp descending. Supports optional filters by user, action type, entity type, and entity ID for security and compliance auditing.", "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", "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", "type": "str", "required": false }, { "name": "entity_type", "type": "str", "required": false, "nullable": true }, { "name": "entity_id", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "details", "type": "dict", "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": "/audit-logs/{auditlog_id}", "summary": "Update Audit Log", "description": "Updates an existing audit log entry. Returns 404 if the audit log does not exist. Returns 400 if no fields are provided for update.", "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", "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": "timestamp", "type": "datetime", "required": false, "nullable": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "details", "type": "dict", "required": false, "nullable": true } ] }, "response": { "schema_name": "AuditlogResponse", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action_type", "type": "str", "required": false }, { "name": "entity_type", "type": "str", "required": false, "nullable": true }, { "name": "entity_id", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "details", "type": "dict", "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": "/audit-logs/{auditlog_id}", "summary": "Delete Audit Log", "description": "Deletes an audit log entry by its unique identifier. Returns 404 if the audit log does not exist.", "path_params": [ { "name": "auditlog_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/configurations", "summary": "Create System Configuration", "description": "Creates a new system configuration setting with a unique key. Returns 409 if a configuration with the same key already exists.", "request_body": { "schema_name": "SystemconfigurationCreate", "fields": [ { "name": "config_key", "type": "str", "required": false }, { "name": "config_value", "type": "str", "required": false }, { "name": "data_type", "type": "ConfigDataType", "required": true, "enum_values": [ "STRING", "INTEGER", "DECIMAL", "BOOLEAN", "JSON" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_editable", "type": "str", "required": false } ] }, "response": { "schema_name": "SystemconfigurationResponse", "fields": [ { "name": "config_key", "type": "str", "required": false }, { "name": "config_value", "type": "str", "required": false }, { "name": "data_type", "type": "ConfigDataType", "required": true, "enum_values": [ "STRING", "INTEGER", "DECIMAL", "BOOLEAN", "JSON" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_editable", "type": "str", "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": "/configurations/{config_id}", "summary": "Get System Configuration by ID", "description": "Retrieves a single system configuration setting by its unique identifier. Returns 404 if the configuration does not exist.", "path_params": [ { "name": "config_id", "type": "str" } ], "response": { "schema_name": "SystemconfigurationResponse", "fields": [ { "name": "config_key", "type": "str", "required": false }, { "name": "config_value", "type": "str", "required": false }, { "name": "data_type", "type": "ConfigDataType", "required": true, "enum_values": [ "STRING", "INTEGER", "DECIMAL", "BOOLEAN", "JSON" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_editable", "type": "str", "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": "/configurations/key/{config_key}", "summary": "Get System Configuration by Key", "description": "Retrieves a single system configuration setting by its unique configuration key. Returns 404 if the configuration does not exist.", "path_params": [ { "name": "config_key", "type": "str" } ], "response": { "schema_name": "SystemconfigurationResponse", "fields": [ { "name": "config_key", "type": "str", "required": false }, { "name": "config_value", "type": "str", "required": false }, { "name": "data_type", "type": "ConfigDataType", "required": true, "enum_values": [ "STRING", "INTEGER", "DECIMAL", "BOOLEAN", "JSON" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_editable", "type": "str", "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": "/configurations", "summary": "List System Configurations", "description": "Returns a paginated list of system configuration settings ordered by configuration key. Supports optional filters by data type and editability status.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "data_type", "type": "ConfigDataType", "required": false }, { "name": "is_editable", "type": "str", "required": false } ], "response": { "schema_name": "SystemconfigurationResponse", "fields": [ { "name": "config_key", "type": "str", "required": false }, { "name": "config_value", "type": "str", "required": false }, { "name": "data_type", "type": "ConfigDataType", "required": true, "enum_values": [ "STRING", "INTEGER", "DECIMAL", "BOOLEAN", "JSON" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_editable", "type": "str", "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": "/configurations/{config_id}", "summary": "Update System Configuration", "description": "Updates an existing system configuration setting. Returns 404 if the configuration does not exist. Returns 400 if the configuration is not editable or if no fields are provided. Returns 409 if the new key conflicts with an existing configuration.", "path_params": [ { "name": "config_id", "type": "str" } ], "request_body": { "schema_name": "SystemconfigurationUpdate", "fields": [ { "name": "config_key", "type": "str", "required": false, "nullable": true }, { "name": "config_value", "type": "str", "required": false, "nullable": true }, { "name": "data_type", "type": "ConfigDataType", "required": false, "nullable": true, "enum_values": [ "STRING", "INTEGER", "DECIMAL", "BOOLEAN", "JSON" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_editable", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "SystemconfigurationResponse", "fields": [ { "name": "config_key", "type": "str", "required": false }, { "name": "config_value", "type": "str", "required": false }, { "name": "data_type", "type": "ConfigDataType", "required": true, "enum_values": [ "STRING", "INTEGER", "DECIMAL", "BOOLEAN", "JSON" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_editable", "type": "str", "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": "/configurations/{config_id}", "summary": "Delete System Configuration", "description": "Deletes a system configuration setting by its unique identifier. Returns 404 if the configuration does not exist. Returns 400 if the configuration is not editable and cannot be deleted.", "path_params": [ { "name": "config_id", "type": "str" } ], "status_code": 200 } ] } ], "enums": { "UserRole": [ "GUEST", "MEMBER", "LIBRARIAN", "ADMINISTRATOR" ], "MembershipStatus": [ "ACTIVE", "SUSPENDED", "EXPIRED", "CANCELLED" ], "AdminLevel": [ "SUPER", "STANDARD" ], "ConditionStatus": [ "EXCELLENT", "GOOD", "FAIR", "POOR", "DAMAGED", "LOST" ], "AvailabilityStatus": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "IN_TRANSIT", "MAINTENANCE", "LOST" ], "LoanStatus": [ "ACTIVE", "RETURNED", "OVERDUE", "LOST" ], "ReservationStatus": [ "PENDING", "READY", "FULFILLED", "CANCELLED", "EXPIRED" ], "PaymentStatus": [ "UNPAID", "PARTIALLY_PAID", "PAID", "WAIVED" ], "PaymentMethod": [ "CASH", "CREDIT_CARD", "DEBIT_CARD", "ONLINE", "CHECK" ], "ConfigDataType": [ "STRING", "INTEGER", "DECIMAL", "BOOLEAN", "JSON" ] } }