Places & Reviews API Handler

Relevant source files

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

• src/app/api/places/[id]/reviews/route.ts
• src/lib/p4n.ts
• src/lib/client.ts
• src/lib/types.ts
• src/components/DetailPanel.tsx
• src/app/api/plan/route.ts

The Places & Reviews API Handler is a core system responsible for fetching, processing, and presenting detailed information about specific locations and their associated user feedback. It acts as a bridge between the frontend components and the Park4Night (P4N) private endpoints, providing a typed interface for retrieving location metadata, user ratings, and textual reviews.

This system ensures that complex data structures from the external P4N API are normalized and safely consumed by the application. It handles authentication state validation, error propagation, and data slicing to optimize performance for the end-user interface.

System Architecture

The architecture follows a tiered approach: the frontend invokes typed client helpers, which call Next.js API route handlers. These handlers utilize a server-side P4N client to interact with external services using the user's session credentials.

The diagram shows the data flow from the UI component through the local API layers to the external Park4Night service.
Sources: src/lib/client.ts:114-116, src/app/api/places/[id]/reviews/route.ts:15-28, src/lib/p4n.ts:285-298

API Endpoints

Review Retrieval

The primary endpoint for this module retrieves a list of recent reviews for a specific location identified by its unique ID.

Method	Endpoint	Description
GET	/api/places/[id]/reviews	Fetches up to 20 recent reviews for the specified placeId.

Parameters:

• id (Path): The unique integer ID of the Park4Night location.

Error Handling:

• 400 Bad Request: Occurs if the id provided is not a finite number.
• 401 Unauthorized: Occurs if the P4N session is invalid or expired.
• 502 Bad Gateway: Occurs for upstream P4N request failures.

Sources: src/app/api/places/[id]/reviews/route.ts:7-35

Data Models

Review Structure

Reviews are represented by a specific interface that captures both the quantitative rating and the qualitative comment.

Field	Type	Description
id	string	Unique identifier for the review.
note	string	The numerical rating given by the user (as a string).
commentaire	string	The actual text of the user's feedback.
uuid	string	Unique ID of the user who wrote the review.
date_creation	string	Timestamp of when the review was posted.

Sources: src/lib/types.ts:192-198

P4nPlace Metadata

Locations themselves contain comprehensive metadata used by the handler to provide context to the reviews.

export interface P4nPlace {
  id: number;
  url: string;
  type: PlaceType;
  name: string;
  rating?: number;
  review?: number; // Total count of reviews
  services: string[];
  activities: string[];
  images?: PlaceImage[];
}

Sources: src/lib/types.ts:31-60

Internal Logic and Processing

Server-Side Fetching

The server-side implementation in lib/p4n.ts performs the actual HTTP request to Park4Night. It utilizes a retry mechanism (fetchWithRetry) to handle transient upstream errors and attaches the required session cookie (PHPSESSID) and headers expected by the site.

export async function getReviews(placeId: number): Promise<Review[]> {
  const res = await fetchWithRetry(
    `${BASE}/services/V4.1/commGet.php?lieu_id=${placeId}`,
    { headers: await baseHeaders() },
  );
  const text = await res.text();
  try {
    const data = JSON.parse(text) as { commentaires?: Review[] };
    return Array.isArray(data.commentaires) ? data.commentaires : [];
  } catch {
    return [];
  }
}

Sources: src/lib/p4n.ts:285-298

Frontend Integration

The DetailPanel component serves as the primary consumer of the Reviews API. It uses a useEffect hook to trigger a fetch whenever a new place is selected on the map. It handles "loading" states by resetting the review state to null before each fetch and implements a cancellation pattern to prevent state updates on unmounted components.

Key UI Behaviors:

• Displays recent reviews (sliced to the first 4) in a vertical list.
• Shows the user rating (note) alongside the user's UUID.
• Uses a CSS line-clamp-3 to limit the length of long review texts in the sidebar.

Sources: src/components/DetailPanel.tsx:40-52, src/components/DetailPanel.tsx:112-123

Summary

The Places & Reviews API Handler provides a robust mechanism for surfacing user-generated content within the trip planning experience. By abstracting the complexities of the Park4Night private API—including base64 decoding, session management, and non-standard JSON responses—it allows the UI to focus on presenting helpful feedback to the user while maintaining high technical reliability through retry logic and server-side proxying.