{ "version": "1.0", "modules": [ { "name": "User Management", "prefix": "/users", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create User", "description": "Creates a new user account with specified role (administrator, librarian, or member). Returns 409 if email already exists. Password must be at least 8 characters with letters and numbers.", "request_body": { "schema_name": "UserCreate", "fields": [ { "name": "email", "type": "EmailStr", "required": true }, { "name": "first_name", "type": "str", "required": false }, { "name": "last_name", "type": "str", "required": false }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "ADMINISTRATOR", "LIBRARIAN", "MEMBER" ] }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "password", "type": "str", "required": false } ] }, "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "str", "required": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/{user_id}", "summary": "Get User by ID", "description": "Retrieves a single user by their unique identifier. Returns 404 if user not found.", "path_params": [ { "name": "user_id", "type": "str" } ], "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "str", "required": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/", "summary": "List Users", "description": "Returns a paginated list of users. Supports optional filtering by role, active status, and text search on name and email fields.", "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 }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "str", "required": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/{user_id}", "summary": "Update User", "description": "Updates user information. Email uniqueness is validated. Password changes require at least 8 characters with letters and numbers. Returns 404 if user not found, 409 if email conflict.", "path_params": [ { "name": "user_id", "type": "str" } ], "request_body": { "schema_name": "UserUpdate", "fields": [ { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "UserRole", "required": false, "nullable": true, "enum_values": [ "ADMINISTRATOR", "LIBRARIAN", "MEMBER" ] }, { "name": "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 }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "str", "required": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{user_id}", "summary": "Delete User", "description": "Deletes a user account. Cascades to associated member record if exists. Returns 404 if user not found.", "path_params": [ { "name": "user_id", "type": "str" } ], "status_code": 204 }, { "method": "POST", "path": "/members", "summary": "Create Member Record", "description": "Creates a member record linked to an existing user. User must have member role. Generates unique membership number automatically. Returns 404 if user not found, 400 if user role is not member, 409 if member record already exists for user.", "request_body": { "schema_name": "MemberCreate", "fields": [ { "name": "membership_status", "type": "MembershipStatus", "required": true, "enum_values": [ "ACTIVE", "SUSPENDED", "EXPIRED", "CANCELLED" ] }, { "name": "membership_tier", "type": "MembershipTier", "required": true, "enum_values": [ "BASIC", "PREMIUM", "GOLD" ] }, { "name": "user_id", "type": "str", "required": true }, { "name": "join_date", "type": "date", "required": true } ] }, "response": { "schema_name": "MemberResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "membership_number", "type": "str", "required": true }, { "name": "join_date", "type": "date", "required": true }, { "name": "membership_status", "type": "str", "required": true }, { "name": "membership_tier", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/members/{member_id}", "summary": "Get Member by ID", "description": "Retrieves a single member by their unique identifier. Returns 404 if member not found.", "path_params": [ { "name": "member_id", "type": "str" } ], "response": { "schema_name": "MemberResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "membership_number", "type": "str", "required": true }, { "name": "join_date", "type": "date", "required": true }, { "name": "membership_status", "type": "str", "required": true }, { "name": "membership_tier", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/members", "summary": "List Members", "description": "Returns a paginated list of members. Supports optional filtering by membership status, tier, and text search on user name, email, and membership number.", "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": "membership_tier", "type": "MembershipTier", "required": false }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "MemberResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "membership_number", "type": "str", "required": true }, { "name": "join_date", "type": "date", "required": true }, { "name": "membership_status", "type": "str", "required": true }, { "name": "membership_tier", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/members/{member_id}", "summary": "Update Member", "description": "Updates member information including status and tier. Returns 404 if member not found.", "path_params": [ { "name": "member_id", "type": "str" } ], "request_body": { "schema_name": "MemberUpdate", "fields": [ { "name": "membership_status", "type": "MembershipStatus", "required": false, "nullable": true, "enum_values": [ "ACTIVE", "SUSPENDED", "EXPIRED", "CANCELLED" ] }, { "name": "membership_tier", "type": "MembershipTier", "required": false, "nullable": true, "enum_values": [ "BASIC", "PREMIUM", "GOLD" ] } ] }, "response": { "schema_name": "MemberResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "membership_number", "type": "str", "required": true }, { "name": "join_date", "type": "date", "required": true }, { "name": "membership_status", "type": "str", "required": true }, { "name": "membership_tier", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/members/{member_id}", "summary": "Delete Member Record", "description": "Deletes a member record. Does not delete the associated user account. Returns 404 if member not found.", "path_params": [ { "name": "member_id", "type": "str" } ], "status_code": 204 }, { "method": "GET", "path": "/members/{member_id}/details", "summary": "Get Member Details", "description": "Retrieves comprehensive member information including user profile, active loans with book titles, pending reservations, and outstanding fines. All related data is eagerly loaded for performance. Returns 404 if member not found.", "path_params": [ { "name": "member_id", "type": "str" } ], "response": { "schema_name": "MemberDetailsResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "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": "str", "required": true }, { "name": "membership_tier", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "user", "type": "MemberDetailsUserResponse", "required": true, "fields": [ { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true } ] }, { "name": "loans", "type": "list[MemberLoanResponse]", "required": true }, { "name": "reservations", "type": "list[MemberReservationResponse]", "required": true }, { "name": "fines", "type": "list[MemberFineResponse]", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/members/register", "summary": "Register New Member", "description": "Complete member registration workflow that creates both user account and member record in a single transaction. Generates unique membership number, sets join date to today, and initializes membership as active basic tier. Returns 409 if email already exists, 400 if role is not member.", "request_body": { "schema_name": "UserCreate", "fields": [ { "name": "email", "type": "EmailStr", "required": true }, { "name": "first_name", "type": "str", "required": false }, { "name": "last_name", "type": "str", "required": false }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "ADMINISTRATOR", "LIBRARIAN", "MEMBER" ] }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "password", "type": "str", "required": false } ] }, "status_code": 201 } ] }, { "name": "Catalog Management", "prefix": "/catalog", "endpoints": [ { "method": "POST", "path": "/publishers", "summary": "Create Publisher", "description": "Creates a new publisher record with contact information. Returns 400 if email format is invalid.", "request_body": { "schema_name": "PublisherCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "website", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "PublisherResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "website", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/publishers/{publisher_id}", "summary": "Get Publisher", "description": "Retrieves a single publisher by ID. Returns 404 if publisher not found.", "path_params": [ { "name": "publisher_id", "type": "str" } ], "response": { "schema_name": "PublisherResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "website", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/publishers", "summary": "List Publishers", "description": "Returns a paginated list of publishers. Supports optional search filter on publisher name.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "PublisherResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "website", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/publishers/{publisher_id}", "summary": "Update Publisher", "description": "Updates an existing publisher record. Only provided fields are updated. Returns 404 if publisher not found.", "path_params": [ { "name": "publisher_id", "type": "str" } ], "request_body": { "schema_name": "PublisherUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "website", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "PublisherResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "website", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/publishers/{publisher_id}", "summary": "Delete Publisher", "description": "Deletes a publisher record. Returns 404 if publisher not found, 409 if publisher has associated books.", "path_params": [ { "name": "publisher_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/authors", "summary": "Create Author", "description": "Creates a new author record with biographical information.", "request_body": { "schema_name": "AuthorCreate", "fields": [ { "name": "first_name", "type": "str", "required": false }, { "name": "last_name", "type": "str", "required": false }, { "name": "biography", "type": "str", "required": false, "nullable": true }, { "name": "birth_date", "type": "date", "required": false, "nullable": true }, { "name": "nationality", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "AuthorResponse", "fields": [ { "name": "first_name", "type": "str", "required": false }, { "name": "last_name", "type": "str", "required": false }, { "name": "biography", "type": "str", "required": false, "nullable": true }, { "name": "birth_date", "type": "date", "required": false, "nullable": true }, { "name": "nationality", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/authors/{author_id}", "summary": "Get Author", "description": "Retrieves a single author by ID. Returns 404 if author not found.", "path_params": [ { "name": "author_id", "type": "str" } ], "response": { "schema_name": "AuthorResponse", "fields": [ { "name": "first_name", "type": "str", "required": false }, { "name": "last_name", "type": "str", "required": false }, { "name": "biography", "type": "str", "required": false, "nullable": true }, { "name": "birth_date", "type": "date", "required": false, "nullable": true }, { "name": "nationality", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/authors", "summary": "List Authors", "description": "Returns a paginated list of authors. Supports optional search filter on first and last name.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "AuthorResponse", "fields": [ { "name": "first_name", "type": "str", "required": false }, { "name": "last_name", "type": "str", "required": false }, { "name": "biography", "type": "str", "required": false, "nullable": true }, { "name": "birth_date", "type": "date", "required": false, "nullable": true }, { "name": "nationality", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/authors/{author_id}", "summary": "Update Author", "description": "Updates an existing author record. Only provided fields are updated. Returns 404 if author not found.", "path_params": [ { "name": "author_id", "type": "str" } ], "request_body": { "schema_name": "AuthorUpdate", "fields": [ { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "biography", "type": "str", "required": false, "nullable": true }, { "name": "birth_date", "type": "date", "required": false, "nullable": true }, { "name": "nationality", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "AuthorResponse", "fields": [ { "name": "first_name", "type": "str", "required": false }, { "name": "last_name", "type": "str", "required": false }, { "name": "biography", "type": "str", "required": false, "nullable": true }, { "name": "birth_date", "type": "date", "required": false, "nullable": true }, { "name": "nationality", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/authors/{author_id}", "summary": "Delete Author", "description": "Deletes an author record. Returns 404 if author not found, 409 if author has associated books.", "path_params": [ { "name": "author_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/genres", "summary": "Create Genre", "description": "Creates a new genre record. Returns 409 if genre name already exists.", "request_body": { "schema_name": "GenreCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "GenreResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "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": "/genres/{genre_id}", "summary": "Get Genre", "description": "Retrieves a single genre by ID. Returns 404 if genre not found.", "path_params": [ { "name": "genre_id", "type": "str" } ], "response": { "schema_name": "GenreResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "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": "/genres", "summary": "List Genres", "description": "Returns a paginated list of genres. Supports optional search filter on genre 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": "GenreResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "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": "/genres/{genre_id}", "summary": "Update Genre", "description": "Updates an existing genre record. Only provided fields are updated. Returns 404 if genre not found, 409 if new name conflicts.", "path_params": [ { "name": "genre_id", "type": "str" } ], "request_body": { "schema_name": "GenreUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "GenreResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "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": "/genres/{genre_id}", "summary": "Delete Genre", "description": "Deletes a genre record. Returns 404 if genre not found, 409 if genre has associated books.", "path_params": [ { "name": "genre_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/books", "summary": "Create Book", "description": "Creates a new book record with bibliographic information. Returns 400 if publisher not found or ISBN invalid, 409 if ISBN already exists.", "request_body": { "schema_name": "BookCreate", "fields": [ { "name": "title", "type": "str", "required": false }, { "name": "isbn", "type": "str", "required": false, "nullable": true }, { "name": "publisher_id", "type": "str", "required": false, "nullable": true }, { "name": "publication_year", "type": "int", "required": false, "nullable": true }, { "name": "edition", "type": "str", "required": false, "nullable": true }, { "name": "language", "type": "str", "required": false }, { "name": "pages", "type": "int", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "cover_image_url", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "BookResponse", "fields": [ { "name": "title", "type": "str", "required": false }, { "name": "isbn", "type": "str", "required": false, "nullable": true }, { "name": "publisher_id", "type": "str", "required": false, "nullable": true }, { "name": "publication_year", "type": "int", "required": false, "nullable": true }, { "name": "edition", "type": "str", "required": false, "nullable": true }, { "name": "language", "type": "str", "required": false }, { "name": "pages", "type": "int", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "cover_image_url", "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": "/books/{book_id}", "summary": "Get Book", "description": "Retrieves a single book by ID. Returns 404 if book not found.", "path_params": [ { "name": "book_id", "type": "str" } ], "response": { "schema_name": "BookResponse", "fields": [ { "name": "title", "type": "str", "required": false }, { "name": "isbn", "type": "str", "required": false, "nullable": true }, { "name": "publisher_id", "type": "str", "required": false, "nullable": true }, { "name": "publication_year", "type": "int", "required": false, "nullable": true }, { "name": "edition", "type": "str", "required": false, "nullable": true }, { "name": "language", "type": "str", "required": false }, { "name": "pages", "type": "int", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "cover_image_url", "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": "/books", "summary": "List Books", "description": "Returns a paginated list of books. Supports optional filters for search, publisher, and language.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "search", "type": "str", "required": false }, { "name": "publisher_id", "type": "str", "required": false }, { "name": "language", "type": "str", "required": false } ], "response": { "schema_name": "BookResponse", "fields": [ { "name": "title", "type": "str", "required": false }, { "name": "isbn", "type": "str", "required": false, "nullable": true }, { "name": "publisher_id", "type": "str", "required": false, "nullable": true }, { "name": "publication_year", "type": "int", "required": false, "nullable": true }, { "name": "edition", "type": "str", "required": false, "nullable": true }, { "name": "language", "type": "str", "required": false }, { "name": "pages", "type": "int", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "cover_image_url", "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": "/books/{book_id}", "summary": "Update Book", "description": "Updates an existing book record. Only provided fields are updated. Returns 404 if book not found, 400 if publisher invalid, 409 if ISBN conflicts.", "path_params": [ { "name": "book_id", "type": "str" } ], "request_body": { "schema_name": "BookUpdate", "fields": [ { "name": "title", "type": "str", "required": false, "nullable": true }, { "name": "isbn", "type": "str", "required": false, "nullable": true }, { "name": "publisher_id", "type": "str", "required": false, "nullable": true }, { "name": "publication_year", "type": "int", "required": false, "nullable": true }, { "name": "edition", "type": "str", "required": false, "nullable": true }, { "name": "language", "type": "str", "required": false, "nullable": true }, { "name": "pages", "type": "int", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "cover_image_url", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "BookResponse", "fields": [ { "name": "title", "type": "str", "required": false }, { "name": "isbn", "type": "str", "required": false, "nullable": true }, { "name": "publisher_id", "type": "str", "required": false, "nullable": true }, { "name": "publication_year", "type": "int", "required": false, "nullable": true }, { "name": "edition", "type": "str", "required": false, "nullable": true }, { "name": "language", "type": "str", "required": false }, { "name": "pages", "type": "int", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "cover_image_url", "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": "/books/{book_id}", "summary": "Delete Book", "description": "Deletes a book record and all associated copies, authors, and genres. Returns 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 details including publisher, authors, genres, and all physical copies. Returns 404 if book not found.", "path_params": [ { "name": "book_id", "type": "str" } ], "response": { "schema_name": "BookDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "isbn", "type": "str", "required": false, "nullable": true }, { "name": "publication_year", "type": "int", "required": false, "nullable": true }, { "name": "edition", "type": "str", "required": false, "nullable": true }, { "name": "language", "type": "str", "required": true }, { "name": "pages", "type": "int", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "cover_image_url", "type": "str", "required": false, "nullable": true }, { "name": "publisher_name", "type": "str", "required": false, "nullable": true }, { "name": "publisher_country", "type": "str", "required": false, "nullable": true }, { "name": "authors", "type": "List[AuthorDetailResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "author_order", "type": "int", "required": true } ] }, { "name": "genres", "type": "List[GenreDetailResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "name", "type": "str", "required": true } ] }, { "name": "copies", "type": "List[BookcopyDetailResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "copy_number", "type": "str", "required": true }, { "name": "status", "type": "BookCopyStatus", "required": true, "enum_values": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "IN_REPAIR", "LOST", "WITHDRAWN" ] }, { "name": "condition", "type": "BookCopyCondition", "required": true, "enum_values": [ "NEW", "GOOD", "FAIR", "POOR", "DAMAGED", "LOST" ] }, { "name": "location", "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": "/book-authors", "summary": "Link Book to Author", "description": "Creates a link between a book and an author with ordering. Returns 400 if book or author not found, 409 if link already exists.", "request_body": { "schema_name": "BookauthorCreate", "fields": [ { "name": "book_id", "type": "str", "required": false }, { "name": "author_id", "type": "str", "required": false }, { "name": "author_order", "type": "int", "required": false } ] }, "response": { "schema_name": "BookauthorResponse", "fields": [ { "name": "book_id", "type": "str", "required": false }, { "name": "author_id", "type": "str", "required": false }, { "name": "author_order", "type": "int", "required": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/book-authors/{bookauthor_id}", "summary": "Get Book-Author Link", "description": "Retrieves a single book-author link by ID. Returns 404 if link not found.", "path_params": [ { "name": "bookauthor_id", "type": "str" } ], "response": { "schema_name": "BookauthorResponse", "fields": [ { "name": "book_id", "type": "str", "required": false }, { "name": "author_id", "type": "str", "required": false }, { "name": "author_order", "type": "int", "required": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/book-authors", "summary": "List Book-Author Links", "description": "Returns a paginated list of book-author links. Supports optional filters for book_id and author_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 }, { "name": "author_id", "type": "str", "required": false } ], "response": { "schema_name": "BookauthorResponse", "fields": [ { "name": "book_id", "type": "str", "required": false }, { "name": "author_id", "type": "str", "required": false }, { "name": "author_order", "type": "int", "required": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/book-authors/{bookauthor_id}", "summary": "Update Book-Author Link", "description": "Updates an existing book-author link. Only provided fields are updated. Returns 404 if link not found, 400 if book or author invalid.", "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": false }, { "name": "author_id", "type": "str", "required": false }, { "name": "author_order", "type": "int", "required": false }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/book-authors/{bookauthor_id}", "summary": "Delete Book-Author Link", "description": "Deletes a book-author link. Returns 404 if link not found.", "path_params": [ { "name": "bookauthor_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/book-genres", "summary": "Link Book to Genre", "description": "Creates a link between a book and a genre. Returns 400 if book or genre not found, 409 if link already exists.", "request_body": { "schema_name": "BookgenreCreate", "fields": [ { "name": "book_id", "type": "str", "required": false }, { "name": "genre_id", "type": "str", "required": false } ] }, "response": { "schema_name": "BookgenreResponse", "fields": [ { "name": "book_id", "type": "str", "required": false }, { "name": "genre_id", "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": "/book-genres/{bookgenre_id}", "summary": "Get Book-Genre Link", "description": "Retrieves a single book-genre link by ID. Returns 404 if link not found.", "path_params": [ { "name": "bookgenre_id", "type": "str" } ], "response": { "schema_name": "BookgenreResponse", "fields": [ { "name": "book_id", "type": "str", "required": false }, { "name": "genre_id", "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": "/book-genres", "summary": "List Book-Genre Links", "description": "Returns a paginated list of book-genre links. Supports optional filters for book_id and genre_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 }, { "name": "genre_id", "type": "str", "required": false } ], "response": { "schema_name": "BookgenreResponse", "fields": [ { "name": "book_id", "type": "str", "required": false }, { "name": "genre_id", "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": "/book-genres/{bookgenre_id}", "summary": "Update Book-Genre Link", "description": "Updates an existing book-genre link. Only provided fields are updated. Returns 404 if link not found, 400 if book or genre invalid.", "path_params": [ { "name": "bookgenre_id", "type": "str" } ], "request_body": { "schema_name": "BookgenreUpdate", "fields": [ { "name": "book_id", "type": "str", "required": false, "nullable": true }, { "name": "genre_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "BookgenreResponse", "fields": [ { "name": "book_id", "type": "str", "required": false }, { "name": "genre_id", "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": "/book-genres/{bookgenre_id}", "summary": "Delete Book-Genre Link", "description": "Deletes a book-genre link. Returns 404 if link not found.", "path_params": [ { "name": "bookgenre_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 condition and location tracking. Returns 400 if book not found, 409 if copy number or barcode already exists.", "request_body": { "schema_name": "BookcopyCreate", "fields": [ { "name": "book_id", "type": "str", "required": false }, { "name": "copy_number", "type": "str", "required": false }, { "name": "barcode", "type": "str", "required": false, "nullable": true }, { "name": "condition", "type": "BookCopyCondition", "required": false, "enum_values": [ "NEW", "GOOD", "FAIR", "POOR", "DAMAGED", "LOST" ] }, { "name": "status", "type": "BookCopyStatus", "required": false, "enum_values": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "IN_REPAIR", "LOST", "WITHDRAWN" ] }, { "name": "location", "type": "str", "required": false, "nullable": true }, { "name": "acquisition_date", "type": "date", "required": true }, { "name": "price", "type": "int", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "BookcopyResponse", "fields": [ { "name": "book_id", "type": "str", "required": false }, { "name": "copy_number", "type": "str", "required": false }, { "name": "barcode", "type": "str", "required": false, "nullable": true }, { "name": "condition", "type": "BookCopyCondition", "required": false, "enum_values": [ "NEW", "GOOD", "FAIR", "POOR", "DAMAGED", "LOST" ] }, { "name": "status", "type": "BookCopyStatus", "required": false, "enum_values": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "IN_REPAIR", "LOST", "WITHDRAWN" ] }, { "name": "location", "type": "str", "required": false, "nullable": true }, { "name": "acquisition_date", "type": "date", "required": true }, { "name": "price", "type": "int", "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": "/book-copies/{bookcopy_id}", "summary": "Get Book Copy", "description": "Retrieves a single book copy by ID. Returns 404 if copy not found.", "path_params": [ { "name": "bookcopy_id", "type": "str" } ], "response": { "schema_name": "BookcopyResponse", "fields": [ { "name": "book_id", "type": "str", "required": false }, { "name": "copy_number", "type": "str", "required": false }, { "name": "barcode", "type": "str", "required": false, "nullable": true }, { "name": "condition", "type": "BookCopyCondition", "required": false, "enum_values": [ "NEW", "GOOD", "FAIR", "POOR", "DAMAGED", "LOST" ] }, { "name": "status", "type": "BookCopyStatus", "required": false, "enum_values": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "IN_REPAIR", "LOST", "WITHDRAWN" ] }, { "name": "location", "type": "str", "required": false, "nullable": true }, { "name": "acquisition_date", "type": "date", "required": true }, { "name": "price", "type": "int", "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": "GET", "path": "/book-copies", "summary": "List Book Copies", "description": "Returns a paginated list of book copies. Supports optional filters for book_id, status, and condition.", "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": "status", "type": "BookCopyStatus", "required": false }, { "name": "condition", "type": "BookCopyCondition", "required": false } ], "response": { "schema_name": "BookcopyResponse", "fields": [ { "name": "book_id", "type": "str", "required": false }, { "name": "copy_number", "type": "str", "required": false }, { "name": "barcode", "type": "str", "required": false, "nullable": true }, { "name": "condition", "type": "BookCopyCondition", "required": false, "enum_values": [ "NEW", "GOOD", "FAIR", "POOR", "DAMAGED", "LOST" ] }, { "name": "status", "type": "BookCopyStatus", "required": false, "enum_values": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "IN_REPAIR", "LOST", "WITHDRAWN" ] }, { "name": "location", "type": "str", "required": false, "nullable": true }, { "name": "acquisition_date", "type": "date", "required": true }, { "name": "price", "type": "int", "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": "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 not found, 400 if book invalid, 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": "copy_number", "type": "str", "required": false, "nullable": true }, { "name": "barcode", "type": "str", "required": false, "nullable": true }, { "name": "condition", "type": "BookCopyCondition", "required": false, "nullable": true, "enum_values": [ "NEW", "GOOD", "FAIR", "POOR", "DAMAGED", "LOST" ] }, { "name": "status", "type": "BookCopyStatus", "required": false, "nullable": true, "enum_values": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "IN_REPAIR", "LOST", "WITHDRAWN" ] }, { "name": "location", "type": "str", "required": false, "nullable": true }, { "name": "acquisition_date", "type": "date", "required": false, "nullable": true }, { "name": "price", "type": "int", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "BookcopyResponse", "fields": [ { "name": "book_id", "type": "str", "required": false }, { "name": "copy_number", "type": "str", "required": false }, { "name": "barcode", "type": "str", "required": false, "nullable": true }, { "name": "condition", "type": "BookCopyCondition", "required": false, "enum_values": [ "NEW", "GOOD", "FAIR", "POOR", "DAMAGED", "LOST" ] }, { "name": "status", "type": "BookCopyStatus", "required": false, "enum_values": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "IN_REPAIR", "LOST", "WITHDRAWN" ] }, { "name": "location", "type": "str", "required": false, "nullable": true }, { "name": "acquisition_date", "type": "date", "required": true }, { "name": "price", "type": "int", "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": "/book-copies/{bookcopy_id}", "summary": "Delete Book Copy", "description": "Deletes a book copy record. Returns 404 if copy not found, 409 if copy has active loans.", "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 member eligibility, book copy availability, active loan limits, and outstanding fines before creating the loan. Returns 400 if validation fails, 404 if member, book copy, or user not found.", "request_body": { "schema_name": "LoanCreate", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "book_copy_id", "type": "str", "required": true }, { "name": "checked_out_by", "type": "str", "required": true }, { "name": "checked_out_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "date", "required": true }, { "name": "returned_date", "type": "datetime", "required": false, "nullable": true }, { "name": "checked_in_by", "type": "str", "required": false, "nullable": true }, { "name": "loan_status", "type": "LoanStatus", "required": true, "enum_values": [ "ACTIVE", "RETURNED", "OVERDUE", "LOST" ] }, { "name": "renewal_count", "type": "int", "required": false, "default": 0 }, { "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": "checked_out_by", "type": "str", "required": true }, { "name": "checked_out_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "date", "required": true }, { "name": "returned_date", "type": "datetime", "required": false, "nullable": true }, { "name": "checked_in_by", "type": "str", "required": false, "nullable": true }, { "name": "loan_status", "type": "LoanStatus", "required": true, "enum_values": [ "ACTIVE", "RETURNED", "OVERDUE", "LOST" ] }, { "name": "renewal_count", "type": "int", "required": false, "default": 0 }, { "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": "/{loan_id}", "summary": "Get Loan", "description": "Retrieves a single loan record 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": "checked_out_by", "type": "str", "required": true }, { "name": "checked_out_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "date", "required": true }, { "name": "returned_date", "type": "datetime", "required": false, "nullable": true }, { "name": "checked_in_by", "type": "str", "required": false, "nullable": true }, { "name": "loan_status", "type": "LoanStatus", "required": true, "enum_values": [ "ACTIVE", "RETURNED", "OVERDUE", "LOST" ] }, { "name": "renewal_count", "type": "int", "required": false, "default": 0 }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/", "summary": "List Loans", "description": "Returns a paginated list of loans. Supports optional filters for member_id, book_copy_id, loan_status, and checked_out_by. 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": "loan_status", "type": "LoanStatus", "required": false }, { "name": "checked_out_by", "type": "str", "required": false } ], "response": { "schema_name": "LoanResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "book_copy_id", "type": "str", "required": true }, { "name": "checked_out_by", "type": "str", "required": true }, { "name": "checked_out_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "date", "required": true }, { "name": "returned_date", "type": "datetime", "required": false, "nullable": true }, { "name": "checked_in_by", "type": "str", "required": false, "nullable": true }, { "name": "loan_status", "type": "LoanStatus", "required": true, "enum_values": [ "ACTIVE", "RETURNED", "OVERDUE", "LOST" ] }, { "name": "renewal_count", "type": "int", "required": false, "default": 0 }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PATCH", "path": "/{loan_id}", "summary": "Update Loan", "description": "Updates an existing loan record. Validates foreign key references if provided. Returns 404 if the loan or any referenced entity does not exist.", "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": "checked_out_by", "type": "str", "required": false, "nullable": true }, { "name": "checked_out_date", "type": "datetime", "required": false, "nullable": true }, { "name": "due_date", "type": "date", "required": false, "nullable": true }, { "name": "returned_date", "type": "datetime", "required": false, "nullable": true }, { "name": "checked_in_by", "type": "str", "required": false, "nullable": true }, { "name": "loan_status", "type": "LoanStatus", "required": false, "nullable": true, "enum_values": [ "ACTIVE", "RETURNED", "OVERDUE", "LOST" ] }, { "name": "renewal_count", "type": "int", "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": "checked_out_by", "type": "str", "required": true }, { "name": "checked_out_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "date", "required": true }, { "name": "returned_date", "type": "datetime", "required": false, "nullable": true }, { "name": "checked_in_by", "type": "str", "required": false, "nullable": true }, { "name": "loan_status", "type": "LoanStatus", "required": true, "enum_values": [ "ACTIVE", "RETURNED", "OVERDUE", "LOST" ] }, { "name": "renewal_count", "type": "int", "required": false, "default": 0 }, { "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 record 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": "Retrieves detailed loan information including member details, book copy details with book and author information, and librarian details. 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": "MemberBasicInfo", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "membership_number", "type": "str", "required": true }, { "name": "user", "type": "UserBasicInfo", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true } ] } ] }, { "name": "book_copy", "type": "BookCopyBasicInfo", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "copy_number", "type": "str", "required": true }, { "name": "barcode", "type": "str", "required": false, "nullable": true }, { "name": "book", "type": "BookBasicInfo", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "isbn", "type": "str", "required": false, "nullable": true }, { "name": "book_authors", "type": "List[BookAuthorInfo]", "required": true, "is_list": true, "item_fields": [ { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] } ] } ] }, { "name": "checked_out_by_user", "type": "UserBasicInfo", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true } ] }, { "name": "checked_in_by_user", "type": "UserBasicInfo", "required": false, "nullable": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true } ] }, { "name": "checked_out_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "date", "required": true }, { "name": "returned_date", "type": "datetime", "required": false, "nullable": true }, { "name": "loan_status", "type": "LoanStatus", "required": true, "enum_values": [ "ACTIVE", "RETURNED", "OVERDUE", "LOST" ] }, { "name": "renewal_count", "type": "int", "required": 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, no excessive fines), book copy availability, creates loan record with calculated due date (14 days), and updates book copy status to checked_out. Returns 400 if validation fails, 404 if member, book copy, or user not found.", "query_params": [ { "name": "member_id", "type": "str", "required": false, "default": null }, { "name": "book_copy_id", "type": "str", "required": false, "default": null }, { "name": "checked_out_by", "type": "str", "required": false, "default": null } ], "response": { "schema_name": "LoanResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "book_copy_id", "type": "str", "required": true }, { "name": "checked_out_by", "type": "str", "required": true }, { "name": "checked_out_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "date", "required": true }, { "name": "returned_date", "type": "datetime", "required": false, "nullable": true }, { "name": "checked_in_by", "type": "str", "required": false, "nullable": true }, { "name": "loan_status", "type": "LoanStatus", "required": true, "enum_values": [ "ACTIVE", "RETURNED", "OVERDUE", "LOST" ] }, { "name": "renewal_count", "type": "int", "required": false, "default": 0 }, { "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. Calculates overdue fines if applicable (up to $25 maximum), updates loan status to returned, updates book copy status to available or reserved if pending reservations exist, and notifies next reservation holder if applicable. Returns 400 if loan is not in active or overdue status, 404 if loan or user not found.", "path_params": [ { "name": "loan_id", "type": "str" } ], "query_params": [ { "name": "checked_in_by", "type": "str", "required": false, "default": null } ], "response": { "schema_name": "LoanResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "book_copy_id", "type": "str", "required": true }, { "name": "checked_out_by", "type": "str", "required": true }, { "name": "checked_out_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "date", "required": true }, { "name": "returned_date", "type": "datetime", "required": false, "nullable": true }, { "name": "checked_in_by", "type": "str", "required": false, "nullable": true }, { "name": "loan_status", "type": "LoanStatus", "required": true, "enum_values": [ "ACTIVE", "RETURNED", "OVERDUE", "LOST" ] }, { "name": "renewal_count", "type": "int", "required": false, "default": 0 }, { "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 Loan", "description": "Renews an active loan by extending the due date by 14 days and incrementing the renewal count. Validates that the loan is active, not overdue, under the renewal limit (maximum 2 renewals), and has no pending reservations. Returns 400 if validation fails, 404 if loan not found.", "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": "checked_out_by", "type": "str", "required": true }, { "name": "checked_out_date", "type": "datetime", "required": true }, { "name": "due_date", "type": "date", "required": true }, { "name": "returned_date", "type": "datetime", "required": false, "nullable": true }, { "name": "checked_in_by", "type": "str", "required": false, "nullable": true }, { "name": "loan_status", "type": "LoanStatus", "required": true, "enum_values": [ "ACTIVE", "RETURNED", "OVERDUE", "LOST" ] }, { "name": "renewal_count", "type": "int", "required": false, "default": 0 }, { "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": "/process-overdue", "summary": "Process Overdue Loans", "description": "Batch processes all overdue loans by updating their status to overdue and creating fine records based on days late and configured rate ($0.50 per day, maximum $25 per book). Returns the count of processed loans.", "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 is active, has not exceeded the maximum of 3 active reservations, has not already reserved the same book, and that the book is currently unavailable. Returns 400 if validation fails, 404 if member or book not found, 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": false }, { "name": "expiration_date", "type": "datetime", "required": true }, { "name": "status", "type": "ReservationStatus", "required": false, "enum_values": [ "PENDING", "READY", "FULFILLED", "CANCELLED", "EXPIRED" ] }, { "name": "notified_date", "type": "datetime", "required": false, "nullable": true }, { "name": "fulfilled_date", "type": "datetime", "required": false, "nullable": true }, { "name": "notes", "type": "str", "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": "notified_date", "type": "datetime", "required": false, "nullable": true }, { "name": "fulfilled_date", "type": "datetime", "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": 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": "notified_date", "type": "datetime", "required": false, "nullable": true }, { "name": "fulfilled_date", "type": "datetime", "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": "GET", "path": "/", "summary": "List Reservations", "description": "Returns a paginated list of reservations. Supports optional filters for 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": "notified_date", "type": "datetime", "required": false, "nullable": true }, { "name": "fulfilled_date", "type": "datetime", "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": true }, "status_code": 200 }, { "method": "PATCH", "path": "/{reservation_id}", "summary": "Update Reservation", "description": "Updates an existing reservation. Validates foreign key references if member_id or book_id are changed. 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": "notified_date", "type": "datetime", "required": false, "nullable": true }, { "name": "fulfilled_date", "type": "datetime", "required": false, "nullable": true }, { "name": "notes", "type": "str", "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": "notified_date", "type": "datetime", "required": false, "nullable": true }, { "name": "fulfilled_date", "type": "datetime", "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": "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 (user first name, last name, email, membership number) and book details (title, ISBN, authors). 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": "notified_date", "type": "datetime", "required": false, "nullable": true }, { "name": "fulfilled_date", "type": "datetime", "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 }, { "name": "member", "type": "MemberInfo", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "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": "email", "type": "str", "required": true } ] } ] }, { "name": "book", "type": "BookInfo", "required": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "title", "type": "str", "required": true }, { "name": "isbn", "type": "str", "required": false, "nullable": 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 reservation by changing its status to CANCELLED. Only reservations with status PENDING or READY can be cancelled. Returns 400 if the reservation is in an invalid state for cancellation, 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": "notified_date", "type": "datetime", "required": false, "nullable": true }, { "name": "fulfilled_date", "type": "datetime", "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": "/{reservation_id}/fulfill", "summary": "Fulfill Reservation", "description": "Marks a reservation as fulfilled when the member picks up the reserved book. Only reservations with status READY can be fulfilled. Sets fulfilled_date to current timestamp and changes status to FULFILLED. Returns 400 if the reservation is not in 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": "notified_date", "type": "datetime", "required": false, "nullable": true }, { "name": "fulfilled_date", "type": "datetime", "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": "/{reservation_id}/notify", "summary": "Notify Reservation Ready", "description": "Notifies a member that their reserved book is ready for pickup. Changes reservation status from PENDING to READY and sets notified_date to current timestamp. Returns 400 if the reservation is not in PENDING 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": "notified_date", "type": "datetime", "required": false, "nullable": true }, { "name": "fulfilled_date", "type": "datetime", "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": "/batch/expire", "summary": "Expire Reservations Batch", "description": "Batch processes reservations that have passed their expiration date. Changes expired reservations from READY to EXPIRED status, then notifies the next member in queue for each book by changing their reservation from PENDING to READY. Returns count of expired and notified reservations.", "status_code": 200 } ] }, { "name": "Fines", "prefix": "/fines", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Fine", "description": "Creates a new fine record for a member. Validates that the member exists and optionally that the loan and waived_by user exist. Returns 404 if any referenced entity is 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": "float", "required": true }, { "name": "reason", "type": "str", "required": true }, { "name": "fine_status", "type": "FineStatus", "required": true, "enum_values": [ "UNPAID", "PAID", "WAIVED", "PARTIAL" ] }, { "name": "issued_date", "type": "date", "required": true }, { "name": "paid_date", "type": "date", "required": false, "nullable": true }, { "name": "waived_date", "type": "date", "required": false, "nullable": true }, { "name": "waived_by", "type": "str", "required": false, "nullable": true }, { "name": "notes", "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": "float", "required": true }, { "name": "reason", "type": "str", "required": true }, { "name": "fine_status", "type": "FineStatus", "required": true, "enum_values": [ "UNPAID", "PAID", "WAIVED", "PARTIAL" ] }, { "name": "issued_date", "type": "date", "required": true }, { "name": "paid_date", "type": "date", "required": false, "nullable": true }, { "name": "waived_date", "type": "date", "required": false, "nullable": true }, { "name": "waived_by", "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": "/{fine_id}", "summary": "Get Fine", "description": "Retrieves 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": "float", "required": true }, { "name": "reason", "type": "str", "required": true }, { "name": "fine_status", "type": "FineStatus", "required": true, "enum_values": [ "UNPAID", "PAID", "WAIVED", "PARTIAL" ] }, { "name": "issued_date", "type": "date", "required": true }, { "name": "paid_date", "type": "date", "required": false, "nullable": true }, { "name": "waived_date", "type": "date", "required": false, "nullable": true }, { "name": "waived_by", "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": "GET", "path": "/", "summary": "List Fines", "description": "Returns a paginated list of fines. Supports optional filtering by member_id and fine_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": "fine_status", "type": "FineStatus", "required": false } ], "response": { "schema_name": "FineResponse", "fields": [ { "name": "member_id", "type": "str", "required": true }, { "name": "loan_id", "type": "str", "required": false, "nullable": true }, { "name": "amount", "type": "float", "required": true }, { "name": "reason", "type": "str", "required": true }, { "name": "fine_status", "type": "FineStatus", "required": true, "enum_values": [ "UNPAID", "PAID", "WAIVED", "PARTIAL" ] }, { "name": "issued_date", "type": "date", "required": true }, { "name": "paid_date", "type": "date", "required": false, "nullable": true }, { "name": "waived_date", "type": "date", "required": false, "nullable": true }, { "name": "waived_by", "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": "PUT", "path": "/{fine_id}", "summary": "Update Fine", "description": "Updates an existing fine record. Validates that any referenced entities (member, loan, waived_by user) exist. Returns 404 if the fine or any referenced entity is 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": "float", "required": false, "nullable": true }, { "name": "reason", "type": "str", "required": false, "nullable": true }, { "name": "fine_status", "type": "FineStatus", "required": false, "nullable": true, "enum_values": [ "UNPAID", "PAID", "WAIVED", "PARTIAL" ] }, { "name": "issued_date", "type": "date", "required": false, "nullable": true }, { "name": "paid_date", "type": "date", "required": false, "nullable": true }, { "name": "waived_date", "type": "date", "required": false, "nullable": true }, { "name": "waived_by", "type": "str", "required": false, "nullable": true }, { "name": "notes", "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": "float", "required": true }, { "name": "reason", "type": "str", "required": true }, { "name": "fine_status", "type": "FineStatus", "required": true, "enum_values": [ "UNPAID", "PAID", "WAIVED", "PARTIAL" ] }, { "name": "issued_date", "type": "date", "required": true }, { "name": "paid_date", "type": "date", "required": false, "nullable": true }, { "name": "waived_date", "type": "date", "required": false, "nullable": true }, { "name": "waived_by", "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": "/{fine_id}", "summary": "Delete Fine", "description": "Deletes a fine record by ID. Returns 404 if the fine does not exist.", "path_params": [ { "name": "fine_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/{fine_id}/details", "summary": "Get Fine Details", "description": "Retrieves detailed information about a fine including member details, associated loan details, and waived_by user information. Returns 404 if the fine does not exist.", "path_params": [ { "name": "fine_id", "type": "str" } ], "response": { "schema_name": "FineDetailsResponse", "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": "float", "required": true }, { "name": "reason", "type": "str", "required": true }, { "name": "fine_status", "type": "FineStatus", "required": true, "enum_values": [ "UNPAID", "PAID", "WAIVED", "PARTIAL" ] }, { "name": "issued_date", "type": "date", "required": true }, { "name": "paid_date", "type": "date", "required": false, "nullable": true }, { "name": "waived_date", "type": "date", "required": false, "nullable": true }, { "name": "waived_by", "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 }, { "name": "member", "type": "MemberSummaryResponse", "required": true, "fields": [ { "name": "user", "type": "MemberUserResponse", "required": true, "fields": [ { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true } ] }, { "name": "membership_number", "type": "str", "required": true } ] }, { "name": "loan", "type": "LoanSummaryResponse", "required": false, "nullable": true, "fields": [ { "name": "book_copy", "type": "LoanBookCopyResponse", "required": true, "fields": [ { "name": "book", "type": "LoanBookResponse", "required": true, "fields": [ { "name": "title", "type": "str", "required": true }, { "name": "isbn", "type": "str", "required": false, "nullable": true } ] } ] }, { "name": "due_date", "type": "date", "required": true }, { "name": "returned_date", "type": "datetime", "required": false, "nullable": true } ] }, { "name": "waived_by_user", "type": "UserSummaryResponse", "required": false, "nullable": true, "fields": [ { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{fine_id}/waive", "summary": "Waive Fine", "description": "Waives a fine by updating its status to waived and recording the waived_by user and date. Returns 400 if the fine is already paid or waived. Returns 404 if the fine or user 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": "float", "required": true }, { "name": "reason", "type": "str", "required": true }, { "name": "fine_status", "type": "FineStatus", "required": true, "enum_values": [ "UNPAID", "PAID", "WAIVED", "PARTIAL" ] }, { "name": "issued_date", "type": "date", "required": true }, { "name": "paid_date", "type": "date", "required": false, "nullable": true }, { "name": "waived_date", "type": "date", "required": false, "nullable": true }, { "name": "waived_by", "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": "/pay", "summary": "Process Fine Payment", "description": "Processes payment for one or more fines. Creates a transaction record and updates fine statuses to paid or partial based on the payment amount. Validates that payment amount does not exceed total outstanding fines and that all fines belong to the specified member. Returns 400 for validation errors or 404 if any referenced entity is not found.", "query_params": [ { "name": "reference_number", "type": "str", "required": false } ], "status_code": 200 } ] }, { "name": "Library Settings", "prefix": "/library-settings", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Library Setting", "description": "Creates a new library setting with a unique key. Returns 409 if a setting with the same key already exists.", "request_body": { "schema_name": "LibrarysettingCreate", "fields": [ { "name": "setting_key", "type": "str", "required": false }, { "name": "setting_value", "type": "str", "required": false }, { "name": "data_type", "type": "SettingDataType", "required": true, "enum_values": [ "STRING", "INTEGER", "DECIMAL", "BOOLEAN", "JSON" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_editable", "type": "bool", "required": false, "default": true } ] }, "response": { "schema_name": "LibrarysettingResponse", "fields": [ { "name": "setting_key", "type": "str", "required": false }, { "name": "setting_value", "type": "str", "required": false }, { "name": "data_type", "type": "SettingDataType", "required": true, "enum_values": [ "STRING", "INTEGER", "DECIMAL", "BOOLEAN", "JSON" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_editable", "type": "bool", "required": false, "default": 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": "/{setting_id}", "summary": "Get Library Setting by ID", "description": "Retrieves a single library setting by its unique ID. Returns 404 if the setting does not exist.", "path_params": [ { "name": "setting_id", "type": "str" } ], "response": { "schema_name": "LibrarysettingResponse", "fields": [ { "name": "setting_key", "type": "str", "required": false }, { "name": "setting_value", "type": "str", "required": false }, { "name": "data_type", "type": "SettingDataType", "required": true, "enum_values": [ "STRING", "INTEGER", "DECIMAL", "BOOLEAN", "JSON" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_editable", "type": "bool", "required": false, "default": 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": "/key/{setting_key}", "summary": "Get Library Setting by Key", "description": "Retrieves a single library setting by its unique key. Returns 404 if the setting does not exist.", "path_params": [ { "name": "setting_key", "type": "str" } ], "response": { "schema_name": "LibrarysettingResponse", "fields": [ { "name": "setting_key", "type": "str", "required": false }, { "name": "setting_value", "type": "str", "required": false }, { "name": "data_type", "type": "SettingDataType", "required": true, "enum_values": [ "STRING", "INTEGER", "DECIMAL", "BOOLEAN", "JSON" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_editable", "type": "bool", "required": false, "default": true }, { "name": "id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/", "summary": "List Library Settings", "description": "Returns a paginated list of library settings. Supports optional search filter on key and description, and filtering by editable status.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "search", "type": "str", "required": false }, { "name": "is_editable", "type": "bool", "required": false } ], "response": { "schema_name": "LibrarysettingResponse", "fields": [ { "name": "setting_key", "type": "str", "required": false }, { "name": "setting_value", "type": "str", "required": false }, { "name": "data_type", "type": "SettingDataType", "required": true, "enum_values": [ "STRING", "INTEGER", "DECIMAL", "BOOLEAN", "JSON" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_editable", "type": "bool", "required": false, "default": 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": "/{setting_id}", "summary": "Update Library Setting", "description": "Updates an existing library setting. Only editable settings can be modified. Returns 400 if the setting is not editable, 404 if not found, or 409 if the new key conflicts with an existing setting.", "path_params": [ { "name": "setting_id", "type": "str" } ], "request_body": { "schema_name": "LibrarysettingUpdate", "fields": [ { "name": "setting_key", "type": "str", "required": false, "nullable": true }, { "name": "setting_value", "type": "str", "required": false, "nullable": true }, { "name": "data_type", "type": "SettingDataType", "required": false, "nullable": true, "enum_values": [ "STRING", "INTEGER", "DECIMAL", "BOOLEAN", "JSON" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_editable", "type": "bool", "required": false, "nullable": true } ] }, "response": { "schema_name": "LibrarysettingResponse", "fields": [ { "name": "setting_key", "type": "str", "required": false }, { "name": "setting_value", "type": "str", "required": false }, { "name": "data_type", "type": "SettingDataType", "required": true, "enum_values": [ "STRING", "INTEGER", "DECIMAL", "BOOLEAN", "JSON" ] }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "is_editable", "type": "bool", "required": false, "default": 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": "/{setting_id}", "summary": "Delete Library Setting", "description": "Deletes a library setting. Only editable settings can be deleted. Returns 400 if the setting is not editable, or 404 if not found.", "path_params": [ { "name": "setting_id", "type": "str" } ], "status_code": 200 } ] } ], "enums": { "UserRole": [ "ADMINISTRATOR", "LIBRARIAN", "MEMBER" ], "MembershipStatus": [ "ACTIVE", "SUSPENDED", "EXPIRED", "CANCELLED" ], "MembershipTier": [ "BASIC", "PREMIUM", "GOLD" ], "BookCopyCondition": [ "NEW", "GOOD", "FAIR", "POOR", "DAMAGED", "LOST" ], "BookCopyStatus": [ "AVAILABLE", "CHECKED_OUT", "RESERVED", "IN_REPAIR", "LOST", "WITHDRAWN" ], "LoanStatus": [ "ACTIVE", "RETURNED", "OVERDUE", "LOST" ], "ReservationStatus": [ "PENDING", "READY", "FULFILLED", "CANCELLED", "EXPIRED" ], "FineStatus": [ "UNPAID", "PAID", "WAIVED", "PARTIAL" ], "TransactionType": [ "FINE_PAYMENT", "MEMBERSHIP_FEE", "DEPOSIT", "REFUND" ], "PaymentMethod": [ "CASH", "CREDIT_CARD", "DEBIT_CARD", "ONLINE", "CHECK" ], "SettingDataType": [ "STRING", "INTEGER", "DECIMAL", "BOOLEAN", "JSON" ] } }