An API built to be used by the for the Hogwart's public library
API url: https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/ENDPOINT_NAME
- Endpoint name
- Description
- File name - Since, code will always be updated even if the read me isn't
- Parameter list -including which method to use such as POST, GET or REQUEST(both)
- httpie command with expected result format to validate the listed information about the endpoint
1. Description:
2. fileName.php --> /api/fileName
3. Parameter list:
4. httpie command:
Verify users:
1. Description: Log the user in and then store the cookie
2. verifyUser.php --> /api/verifyUser
3. Parameter list:
Accepts POST variable: username, password, userType
userType (valid values) : professor, student, headmaster, user, librarian
4. httpie command:
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/verifyUser username='hGranger' password='actors1Reserve9Vegas7Portugal9Plants' userType='librarian'
Registering user
1. Description: Users can register for their own account if they have a registration passcode
2. userManagement/addUser.php --> /api/userManagement/addUsers
3. Parameter list:
Accepts POST variable: fname, lname, userType, username, password, passcode
// IF user is a student we need parameter of house and major
// If professor we need department
userType (valid values) : professor, student, headmaster
4. httpie command:
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/userManagement/addUser username='JKRowling' password='whats in a dream' userType='professor' fname='Joanne' lname='Rowling' department='English' passcode='ENTER_THE_PASSCODE'
Note: it might make sense to separate the endpoints for different user types.
Check username
1. Description: Check if username/email is in database
2. userManagement/checkUserName.php --> /api/userManagement/checkUserName
3. Parameter list:
Accepts POST variable: username
4. httpie command:
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/userManagement/checkUserName username='Snape1@hogwarts.com'
Reset user password
1. Description: The headmaster has the power to reset user's passwords
2. userManagement/resetPassword.php --> /api/userManagement/resetPassword
3. Parameter list:
Accepts POST variable: uID, uPassword, developerPassword
4. httpie command:
http -f --session=/tmp/session.json POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/userManagement/resetPassword uID=userID uPassword='newPasss' developerPassword='devPass'
Queries for charts accessible to all users
1. Description: Queries used to create charts and table that give meta
information about the system. These queries can be accessed by guest users as well
2. chart/guestCharts.php --> /api/chart/guestCharts
3. Parameter list:
Accepts request variable: chartType
Current charts are: category, major, allTime, houseFine,
4. httpie command:
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/chart/guestCharts chartType='houseFine'
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/chart/guestCharts chartType='category'
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/chart/guestCharts chartType='major'
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/chart/guestCharts chartType='allTime'
Authenticated Queries for charts
1. Description: Queries used to create charts and table that give meta
information about the system. These can be accessed by the users with the correct privilege.
privilege list - where headmaster can access result from any query
headmaster -> librarian -> professor -> student
This API also allows default values for some users
So, if logged in as a student - you will receive result for the default student query
This is useful if the front-end is flexible and can handle different queries
Then we can change the default query in the back-end and the front-end will automatically
be updated. However, this will cause them to be coupled.
For this reason I recommend not relying on the default query and have only
included them for backward compatibility.
2. chart/loggedInChart.php --> /api/chart/loggedInChart
3. Parameter list:
Accepts POST variable: chartType
if headmaster
valid values: reservationList, fineList, activeList
if librarian
valid values: unusedList, lostList
if professor
valid values: activityPerMajorAndDepartment
if student
valid values: numBooksPerCategory
4. httpie command:
if headmaster
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/chart/loggedInChart chartType='reservationList'
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/chart/loggedInChart chartType='fineList'
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/chart/loggedInChart chartType='activeList'
If librarian
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/chart/loggedInChart chartType='unusedList'
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/chart/loggedInChart chartType='lostList'
If professor
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/chart/loggedInChart chartType='activityPerMajorAndDepartment'
If student
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/chart/loggedInChart chartType='numBooksPerCategory'
Authenticated Queries for lists
1. Description: Queries used to create lists and tables that give meta information
about the system. These can be only accessed by the users of the correct userType.
So, to view the librarian queries you have to be a librarian.
2. loadList.php --> /api/loadList
3. Parameter list:
Accepts POST variable: listType
if headmaster
valid values: loadPotentialLibrarian, loadLibrarian, loadCourses, loadEnrollment, loadStudents, loadProfessor, loadMember, loadUsers
if librarian
valid values: loadPotentialBorrower, loadFinedMember, loadBookBarcode
4. httpie command:
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/loadList listType='loadPotentialLibrarian'
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/loadList listType='loadLibrarian'
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/loadList listType='loadCourses'
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/loadList listType='loadEnrollment'
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/loadList listType='loadStudents'
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/loadList listType='loadProfessor'
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/loadList listType='loadMember'
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/loadList listType='loadUsers'
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/loadList listType='loadPotentialBorrower'
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/loadList listType='loadFinedMember'
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/loadList listType='loadBookBarcode'
Viewing checked out books
1. Description: Users can view books checked on their account
2. user/userCheckedOut.php --> /api/user/userCheckedOut
3. Parameter list:
4. httpie command:
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/user/userCheckedOut
Viewing fines on user's account
1. Description: Users can view the fines on their account
2. user/userFines.php --> /api/user/userFines
3. Parameter list:
Accepts POST variable: listType: distinguish if we just want the total fine or a
list of the transaction with fines
listType=getOutstandingFineOnAccount - retrieves the amount the user owes
listType=getTransactionWithFines - retrieves all fines where the user had a fine
Future - May not show fines that are no longer relevant - e.g. over the
total outstanding fine on the user's account
4. httpie command:
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/user/userFines listType='getOutstandingFineOnAccount'
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/user/userFines listType='getTransactionWithFines'
Viewing holds on user account
1. Description: Users can view and track their holds
2. user/userHolds.php --> /api/user/userHolds
3. Parameter list:
4. httpie command:
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/user/userHolds
Add course
1. Description: Headmaster can add courses to the database
2. headmaster/addCourses.php --> /api/headmaster/addCourses
3. Parameter list: courseName & professorID
Accepts POST variable:
4. httpie command:
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/headmaster/addCourses courseName='The language of magic' professorID=397
Delete course
1. Description: Headmaster can delete courses from the database
2. headmaster/deleteCourses.php --> /api/headmaster/deleteCourses
3. Parameter list:
Accepts POST variable: courseID
4. httpie command:
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/headmaster/deleteCourses courseID=26
Enroll students in courses
1. Description: The headmaster can enroll students into the courses they are going
to take this semester
2. headmaster/addEnrollment.php --> /api/headmaster/addEnrollment
3. Parameter list:
Accepts POST variable: courseID, studentID
4. httpie command:
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/headmaster/addEnrollment courseID=4 studentID=18
Remove student from course
1. Description: The headmaster can also remove students from their classes
2. headmaster/deleteEnrollment.php --> /api/headmaster/deleteEnrollment
3. Parameter list:
Accepts POST variable: enrollmentNumber
4. httpie command:
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/headmaster/deleteEnrollment enrollmentNumber=18
Make user's librarians
1. Description: Allow headmaster to grant librarian privileges to users
2. headmaster/addLibrarian.php --> /api/headmaster/addLibrarian
3. Parameter list:
Accepts POST variable: userID
4. httpie command: http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/headmaster/addLibrarian userID=589
Remove librarian
1. Description: This api will be used to revoke librarian privileges from an account.
In the back-end we mark the librarian account as deactivated instead of
deleting them, to ensure integrity
2. headmaster/deleteLibrarian.php --> /api/headmaster/deleteLibrarian
3. Parameter list:
Accepts POST variable: userID
4. httpie command:
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/headmaster/deleteLibrarian userID=589
Check out book
1. Description: Endpoint used by librarian's to checkout book to users
2. librarian/checkOut.php --> /api/librarian/checkOut
3. Parameter list:
Accepts POST variable: bookBarcode, borrowedBy
4. httpie command: http -f --session=/tmp/session.json POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/librarian/checkOut bookBarcode=902773774468 borrowedBy=2
Return book
1. Description: Endpoint used by librarian's to return book for users. When book is returned we add fine to the user's account, store the librarian who returned the book. We also decrement the numberOfBooks on the members account. And, if the book is on hold, we reserve the book to the first user in line.
2. librarian/returnBook.php --> /api/librarian/returnBook
3. Parameter list:
Accepts POST variable: bookBarcode
4. httpie command:
http -f --session=/tmp/session.json POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/librarian/returnBook bookBarcode=902773774468
Searching catalog
1. Description: API used to search the catalog. You can search for books title,
author, ISBN, tag or keyword which searches through all of the other search method
2. library/searchCatalogue.php --> /api/library/searchCatalogue
3. Parameter list:
Accepts REQUEST variable: searchType, searchWord
searchType (valid values): keyword, title, author, ISBN, tag
4. httpie command:
User pay off fine
1. Description: A librarian can authorize a payment toward user fines
2. librarian/payFine.php --> /api/librarian/payFine
3. Parameter list:
Accepts POST variable: pay, userID
4. httpie command:
http -f --session=/tmp/session.json POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/librarian/payFine pay=40 userID=5
Put a hold on a book
1. Description: Endpoint handles the case where either a user tries to place a hold on a book,a librarian places a hold on the behalf of a user or either of those two cases where the book is also reserved for a class
2. library/holdBook.php --> /api/library/holdBook
3. Parameter list:
Accepts POST variable: bookISBN
if librarian is placing hold on behalf of user: userID
If hold is for a book reserved for course: courseID
4. httpie command:
http -f --session=/tmp/session.json POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/library/holdBooks userID=500 bookISBN='978-1-6685-9857-3'
Cancel a hold
1. Description: Allow user to cancel a hold or a librarian to cancel a hold on their behalf. If there are other users waiting for a book, the book will be reserved for them.
2. library/cancelHoldBooks.php --> /api/library/cancelHoldBooks
3. Parameter list:
Accepts POST variable: holdID
if librarian: userID
4. httpie command:
http -f --session=/tmp/session.json POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/library/cancelHoldBooks userID=50 holdID=14
Renew a book
1. Description: Allow users to renew books if there are no holds on the book. A book can be renewed a maximum of two times
2. library/renewBooks.php --> /api/library/renewBooks
3. Parameter list:
Accepts POST variable: bookBarcode, userID (if librarian)
4. httpie command:
http -f --session=/tmp/session.json POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/library/renewBooks bookBarcode=902773774468 userID=2
Report book as lost
1. Description: A user can report a book as lost and then pay off a portion of the cost of buying the book. A librarian CANNOT report a book as lost on behalf of a user
2. library/lostBook.php --> /api/library/lostBook
3. Parameter list:
Accepts POST variable: bookBarcode
4. httpie command:
http -f --session=/tmp/session.json POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/library/lostBook bookBarcode=902773770485
Professor reserves book copies for class
1. Description: Professors can reserve up to 10 of any book for any of their course, this will make it so only students of that class can place a hold and checkout those books.
2. reservation/addReservation.php --> /api/reservation/addReservation
3. Parameter list:
Accepts POST variable: courseID, bookISBN, numCopies - userID(if librarian)
4. httpie command:
http -f --session=/tmp/session.json POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/reservation/addReservation courseID=18 bookISBN='978-0-6514-7775-8' numCopies=10 userID=577
Professor cancels reservation for book copies
1. Description: Remove all copies of the reserved book for the given course
2. reservation/deleteReservation.php --> /api/reservation/deleteReservation
3. Parameter list:
Accepts POST variable: courseID, bookISBN - userID(if librarian)
4. httpie command:
http -f --session=/tmp/session.json POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/reservation/deleteReservation courseID=18 bookISBN='978-0-6514-7775-8' userID=577
View books to reserve and list of current reservations
1. Description: Lists related to reserving books, will be re factored into separate endpoint later
2. reservation/reservationList.php --> /api/reservation/reservationList
3. Parameter list:
Accepts POST variable: listType
listType valid values: loadReservedBooks, loadCoursesStudent, loadCoursesProfessor, loadAvailableBooks, loadProfessor
for loadReservedBooks - we need a courseID - these should really be their own endpoint...
If librarian: we must put in userID
4. httpie command:
- http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/reservation/reservationList listType='loadCoursesProfessor' userID=3
- http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/reservation/reservationList listType='loadAvailableBooks'
- http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/reservation/reservationList listType='loadProfessor'
check if user is logged in
1. Description: returns true if user is logged in and false if they are not
2. user/isLoggedIn.php --> /api/user/isLoggedIn
3. Parameter list:
4. httpie command:
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/user/isLoggedIn
logout user
1. Description: Logout the user
2. user/logout.php --> /api/user/logout
3. Parameter list:
4. httpie command:
http --session=/tmp/session.json --form POST https://arif115.myweb.cs.uwindsor.ca/hogwartslibrary/api/user/logout