API Endpoints

Relevant source files

The following files were used as context for generating this wiki page:

• finder/api.py
• finder/urls.py
• finder/views.py
• finder/static/finder/js/scripts.js
• finder/models.py
• README.md

The Campuspal Room Finder application utilizes a combination of a dedicated RESTful API and an AJAX-enabled view to create a dynamic and responsive user experience. These endpoints are responsible for fetching detailed room information and handling search queries without requiring full page reloads. The primary goal is to provide the frontend with structured data (JSON) for room details and pre-rendered HTML for search results, minimizing client-side processing and ensuring a fast interface.

The architecture separates the concern of fetching detailed data for a single entity (a room's schedule) into a clean JSON API, while the more complex search and timeline generation logic is handled by a view that returns an HTML partial. This approach leverages Django's templating engine for the complex timeline view and provides a standard API for modal pop-ups.

Sources: README.md:100-113, 119-126, finder/api.py, finder/views.py:108-111

API Architecture Overview

The frontend JavaScript interacts with two distinct backend endpoints. A dedicated JSON API at /api/room/... provides data for the room details modal, while an AJAX-aware view at /search/ handles the main search functionality, returning an HTML partial to update the timeline display.

This diagram illustrates the high-level interaction between the client and the server-side endpoints.

Endpoints

GET /api/room/<int:room_id>/

This endpoint provides detailed information and a full-day schedule for a single room. It is designed to be called via an AJAX GET request from the frontend to populate a modal window with the room's profile.

Sources: README.md:100-113, finder/api.py

URL Configuration

The endpoint is registered in the application's URL configuration.

• File: finder/urls.py
• Code: path("api/room/<int:room_id>/", api.room_details, name="room_details")

Sources: README.md:162-163

Request

The request requires the room_id as part of the URL path and accepts a day as a query parameter.

Parameter	Type	Location	Description
room_id	integer	URL Path	The primary key of the Room object to fetch.
day	string	Query String	The day to fetch the schedule for (e.g., "Mon").

Sources: finder/api.py:1-13, finder/static/finder/js/scripts.js:45-46

Processing Logic

The api.room_details function handles the request. The logic flow is as follows:

1. Retrieves the Room instance from the database using the provided room_id.
2. Fetches all associated ClassSchedule objects for that room on the specified day.
3. Constructs a timeline list representing the day from 7:00 to 23:00. This list contains dictionaries for "free" and "booked" time blocks.
4. Serializes the room's details (name, building, capacity, amenities) and the generated timeline into a JSON object.
5. Returns a JsonResponse to the client. Time values are formatted as HH:MM strings to ensure correct parsing by JavaScript.

The following sequence diagram shows the interaction for a room_details request.

Response Payload

The endpoint returns a JSON object with room details and its daily timeline.

Key	Type	Description
room	object	Contains details about the room.
room.name	string	The name of the room (e.g., "HH101").
room.building	string	The building the room is in.
room.capacity	integer	The seating capacity of the room.
room.amenities	array	A list of strings representing amenities (e.g., ["Projector"]).
timeline	array	An array of objects representing time blocks throughout the day.
timeline[].type	string	The type of block: "free" or "booked".
timeline[].start	string	The start time of the block in "HH:MM" format.
timeline[].end	string	The end time of the block in "HH:MM" format.
timeline[].course	string	The course name if the block is "booked". Present only for booked blocks.

Sources: finder/api.py:1-13, finder/models.py:7-11

POST /search/

This URL endpoint serves a dual purpose. For standard GET requests, it renders the main search page. For POST requests made with an X-Requested-With: XMLHttpRequest header, it functions as an AJAX endpoint to perform a room search and returns an HTML fragment containing the results.

Sources: finder/views.py:108-111, README.md:119-122

URL Configuration

The endpoint is mapped to the search_rooms view.

• File: finder/urls.py
• Code: path("search/", views.search_rooms, name="search_rooms")

Request

The request is a POST containing form data for the search criteria. The X-Requested-With header is crucial for triggering the AJAX response.

Parameter	Type	Location	Description
csrfmiddlewaretoken	string	Form Data	Django's CSRF token.
building	string	Form Data	The building to search in, or "ALL".
day	string	Form Data	The day to search on (e.g., "Mon").
time	string	Form Data	(Optional) The start time for the search (e.g., "09:00").
duration	integer	Form Data	(Optional) The duration in minutes required.

Sources: finder/views.py:21-26, finder/static/finder/js/scripts.js:14-20

Processing Logic

The search_rooms view in finder/views.py contains the logic. When an AJAX request is detected:

1. The RoomSearchForm is validated.
2. It queries for all rooms matching the building criteria.
3. For each room, it constructs a full-day timeline (7:00 - 23:00) by finding "free" gaps between ClassSchedule entries.
4. If time and duration are provided, it categorizes rooms into available_rooms and unavailable_rooms lists. A room is "available" if the requested time slot fits entirely within a single "free" block.
5. It calculates start_percentage and width_percentage for each timeline block to be used by the CSS for rendering the visual timeline.
6. The view renders the finder/timeline_partial.html template with the processed data.
7. The final rendered HTML is returned in the response body.

This flowchart shows the logic for an AJAX search request.

Response Payload

The response is not JSON, but an HTTP response with Content-Type: text/html. The body contains the rendered HTML of the finder/timeline_partial.html template, which is ready to be injected directly into the DOM by the client-side JavaScript.

Sources: finder/views.py:108-111, finder/static/finder/js/scripts.js:21-24

Data Models

The data returned by the API endpoints originates from the Room and ClassSchedule models.

This ER diagram shows the one-to-many relationship between Room and ClassSchedule.