4/28/25, 1:06 PM StackEdit

Tour Operation API Documentation with

Statistical Analysis

This document details the RESTful API endpoints for managing tour operations, built
with Flask and MongoDB Atlas. The APIs support creating, reading, updating, and
deleting tour data, as well as querying tours by city. A statistical analysis of the API
endpoints is included to provide insights into their structure and usage.

Base URL

https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app

API Endpoints

1. Hello World

Endpoint: /

Method: GET

Description: Checks API status and MongoDB connection.

Response:

200 OK: Greeting with MongoDB connection status.

Example:

curl https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app/

https://stackedit.io/app# 1/50
4/28/25, 1:06 PM StackEdit

Response: Hello World! MongoDB is connected

2. Get All Tours

Endpoint: /gettours

Method: GET

Description: Retrieves all tours.

Response:

200 OK: JSON array of tours.

500 Internal Server Error: Connection issues.

Example:

curl https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app/gettours

Response:

[{"TourID": "T001", "TourName": "European Adventure", "Duration": "7 d

3. Get Tour by ID

Endpoint: /gettour/<tour_id>

Method: GET

Description: Retrieves a tour by TourID .

Parameters:

tour_id (path, string): e.g., T001 .

Response:

200 OK: Tour JSON object.

404 Not Found: Tour not found.

https://stackedit.io/app# 2/50
4/28/25, 1:06 PM StackEdit

500 Internal Server Error: Connection issues.

Example:

curl https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app/gettour/T00

Response:

{"TourID": "T001", "TourName": "European Adventure", "Duration": "7 da

4. Add New Tour

Endpoint: /addtour

Method: POST

Description: Adds a new tour.

Request Body (JSON):

{
"TourID": "T002",
"TourName": "Asian Escape",
"Duration": "5 days",
"StartDate": "2025-07-01",
"EndDate": "2025-07-05",
"Destinations": ["Tokyo", "Kyoto"]
}

Response:

200 OK: Success message with inserted ID.

400 Bad Request: Missing required fields.
500 Internal Server Error: Connection issues.

Example:

curl -X POST https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app/add

https://stackedit.io/app# 3/50
4/28/25, 1:06 PM StackEdit

Response:

{"message": "Tour added successfully", "id": "671f3b4c9d2e4a5b6c7d8e9f

5. Update Tour by ID

Endpoint: /updatetour/<tourid>

Method: PUT

Description: Updates a tour by TourID .

Parameters:

tourid (path, string): e.g., T001 .

Request Body (JSON):

{"TourName": "Updated European Adventure", "Duration": "8 days"}

Response:

200 OK: Success message.

400 Bad Request: No data provided.
404 Not Found: Tour not found.
500 Internal Server Error: Connection issues.

Example:

curl -X PUT https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app/upda

Response:

{"message": "Tour updated successfully"}

https://stackedit.io/app# 4/50
4/28/25, 1:06 PM StackEdit

6. Find Nearby Tours by City

Endpoint: /nearbytours/<city>

Method: GET

Description: Retrieves tours including the specified city in Destinations .

Parameters:

city (path, string): e.g., Paris .

Response:

200 OK: Array of matching tours.

404 Not Found: No tours found.
500 Internal Server Error: Connection issues.

Example:

curl https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app/nearbytours

Response:

{"NearbyTours": [{"TourID": "T001", "TourName": "European Adventure",

7. Delete Tour by Name

Endpoint: /deletetourbyname/<tour_name>

Method: DELETE

Description: Deletes a tour by TourName .

Parameters:

tour_name (path, string): e.g., European Adventure .

Response:

https://stackedit.io/app# 5/50
4/28/25, 1:06 PM StackEdit

200 OK: Success message.

404 Not Found: Tour not found.
500 Internal Server Error: Connection issues.

Example:

curl -X DELETE https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app/d

Response:

{"message": "Tour 'European Adventure' deleted successfully"}

Statistical Analysis of API Endpoints

Overview

The API consists of 7 endpoints supporting CRUD (Create, Read, Update, Delete)
operations and a specialized query by city. Below is a statistical breakdown of the
endpoints based on their HTTP methods, functionality, and hypothetical usage patterns.

Endpoint Distribution by HTTP Method

HTTP Method

Count

Percentage

Endpoints

GET

57.14%

https://stackedit.io/app# 6/50
4/28/25, 1:06 PM StackEdit

/ , /gettours , /gettour/<tour_id> , /nearbytours/<city>

POST

14.29%

/addtour

PUT

14.29%

/updatetour/<tourid>

DELETE

14.29%

/deletetourbyname/<tour_name>

Insight: The majority (57.14%) of endpoints are read-only (GET), indicating a focus on
data retrieval. Write operations (POST, PUT, DELETE) are equally distributed, each
representing 14.29%.

Endpoint Functionality

Functionality

Count

Percentage

Endpoints

Read

https://stackedit.io/app# 7/50
4/28/25, 1:06 PM StackEdit

57.14%

/ , /gettours , /gettour/<tour_id> , /nearbytours/<city>

Create

14.29%

/addtour

Update

14.29%

/updatetour/<tourid>

Delete

14.29%

/deletetourbyname/<tour_name>

Insight: Read operations dominate, aligning with typical API usage where data retrieval
is more frequent than modification.

Response Status Codes

Each endpoint supports multiple status codes based on success or error conditions:

200 OK: All endpoints (success case).

404 Not Found: /gettour/<tour_id> , /updatetour/<tourid> ,
/nearbytours/<city> , /deletetourbyname/<tour_name> .
400 Bad Request: /addtour , /updatetour/<tourid> .
500 Internal Server Error: All endpoints (connection issues).

Status Code

Endpoints Involved
https://stackedit.io/app# 8/50
4/28/25, 1:06 PM StackEdit

Percentage of Endpoints

200

100%

404

57.14%

400

28.57%

500

100%

Insight: All endpoints can return 200 (success) and 500 (server error), reflecting robust
error handling. 404 is common in endpoints with specific queries, and 400 is limited to
endpoints with input validation.

Hypothetical Usage Statistics

Assuming a sample of 1,000 API requests over a week (hypothetical, as no real data is
provided):

Endpoint

Estimated Requests

Percentage

Notes

https://stackedit.io/app# 9/50
4/28/25, 1:06 PM StackEdit

100

10%

Used for health checks.

/gettours

300

30%

Common for browsing all tours.

/gettour/<tour_id>

200

20%

Frequent for specific tour details.

/nearbytours/<city>

250

25%

Popular for location-based queries.

/addtour

50

5%

Less frequent, used by admins.

/updatetour/<tourid>

50

5%

Infrequent, for tour updates.

https://stackedit.io/app# 10/50
4/28/25, 1:06 PM StackEdit

/deletetourbyname/<tour_name>

50

5%

Rare, for tour removal.

Insight: Read endpoints ( /gettours , /gettour/<tour_id> , /nearbytours/<city> )

account for 75% of hypothetical usage, reflecting typical user behavior. Write
operations are less frequent, likely restricted to administrative tasks.

Parameter Usage

Endpoint

Parameters

Type

Required

/gettour/<tour_id>

tour_id

Path

Yes

/updatetour/<tourid>

tourid

Path

Yes

/nearbytours/<city>

city

Path

https://stackedit.io/app# 11/50
4/28/25, 1:06 PM StackEdit

Yes

/deletetourbyname/<tour_name>

tour_name

Path

Yes

/addtour

JSON body

Body

Yes (TourID, TourName, Duration, StartDate, EndDate)

/updatetour/<tourid>

JSON body

Body

Yes (at least one field)

Insight: 4 endpoints use path parameters for specific queries, while 2 require JSON
bodies for data submission. All parameters are required, ensuring strict input validation.

Testing the APIs

1. Using curl :
Execute commands as shown in the examples above.
Ensure proper URL encoding for path parameters (e.g.,
European%20Adventure ).
2. Using Postman:
Import endpoints and set the base URL.
Configure HTTP methods and JSON bodies for POST/PUT requests.
Verify responses for expected status codes and data.
3. Using a Browser:
https://stackedit.io/app# 12/50
4/28/25, 1:06 PM StackEdit

Access GET endpoints directly (e.g., /gettours , /nearbytours/Paris ).

Example: https://idx-mywebapi-34600209-e5q6islzdq-
df.a.run.app/gettours

Notes

MongoDB Connection: All endpoints perform a ping to verify MongoDB Atlas

connectivity, ensuring reliability.
Error Handling: Comprehensive error handling with 400, 404, and 500 status
codes.
Security: Ensure the MongoDB URI is securely stored (e.g., as an environment
variable) in production.
Scalability: The API supports basic CRUD and query operations, suitable for small
to medium-scale applications. For high traffic, consider adding rate limiting and
caching.

Conclusion

The Tour Operation API provides a robust interface for managing tour data, with a
strong emphasis on read operations (57.14% of endpoints). The statistical analysis
highlights a balanced design with comprehensive error handling and a focus on user-
friendly data retrieval. Hypothetical usage suggests read-heavy traffic, typical for travel-
related APIs. To enhance the API, consider adding authentication, pagination for
/gettours , and additional query filters for /nearbytours/<city> .

User Operation API Documentation

This document outlines the RESTful API for managing user operations, built with Flask
and MongoDB Atlas. The API supports user registration, login, data retrieval, updates,

https://stackedit.io/app# 13/50
4/28/25, 1:06 PM StackEdit

and deletion with role-based access control. A statistical analysis provides insights into
the API’s structure and usage patterns.

Base URL

https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app

API Endpoints

1. List All Users (Public)

Endpoint: /getusersbyall

Method: GET

Description: Retrieves all users’ data without access restrictions.

Response:

200 OK: Array of user objects.

500 Internal Server Error: Connection failure.

Example:

curl https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app/getusersbya

Response:

[
{
"UserID": "123e4567-e89b-12d3-a456-426614174000",
"Email": "[email protected]",
"PasswordHashed": "hashed_password",

https://stackedit.io/app# 14/50
4/28/25, 1:06 PM StackEdit

"FullName": "John Doe",

"AccountCreatedAt": "2025-04-28T10:00:00Z",
"LastLoginDate": "2025-04-28T12:00:00Z",
"LogoutTime": null,
"UserRole": "customer",
"EmailVerified": false,
"AccountStatus": "active"
}
]

2. List All Users (Restricted)

Endpoint: /getusers

Method: GET

Description: Retrieves all users’ data, accessible only to admins and travel agents.

Headers:

User-Role : Role of the requesting user ( admin or travel_agent ).

Response:

200 OK: Array of user objects.

403 Forbidden: Invalid or missing role.
500 Internal Server Error: Connection failure.

Example:

curl -H "User-Role: admin" https://idx-mywebapi-34600209-e5q6islzdq-df

Response:

[
{
"UserID": "123e4567-e89b-12d3-a456-426614174000",
"Email": "[email protected]",
"PasswordHashed": "hashed_password",
"FullName": "John Doe",
"AccountCreatedAt": "2025-04-28T10:00:00Z",
https://stackedit.io/app# 15/50
4/28/25, 1:06 PM StackEdit

"LastLoginDate": "2025-04-28T12:00:00Z",
"LogoutTime": null,
"UserRole": "customer",
"EmailVerified": false,
"AccountStatus": "active"
}
]

3. Get User by ID

Endpoint: /getuser/<user_id>

Method: GET

Description: Retrieves a specific user’s data by user_id , accessible only to

admins and travel agents.

Parameters:

user_id (path, string): Unique user identifier (e.g., 123e4567-e89b-12d3-

a456-426614174000 ).

Headers:

User-Role : Role of the requesting user ( admin or travel_agent ).

Response:

200 OK: User object.

403 Forbidden: Invalid or missing role.
404 Not Found: User not found.
500 Internal Server Error: Connection failure.

Example:

curl -H "User-Role: admin" https://idx-mywebapi-34600209-e5q6islzdq-df

Response:

https://stackedit.io/app# 16/50
4/28/25, 1:06 PM StackEdit

{
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"email": "[email protected]",
"full_name": "John Doe",
"account_created_at": "2025-04-28T10:00:00Z",
"last_login_date": "2025-04-28T12:00:00Z",
"logout_time": null,
"user_role": "customer",
"email_verified": false,
"account_status": "active"
}

4. Register User

Endpoint: /signup

Method: POST

Description: Creates a new user with the default role of customer .

Request Body (JSON):

{
"email": "[email protected]",
"password": "securepassword123",
"full_name": "John Doe"
}

Response:

201 Created: Success message.

400 Bad Request: Email already registered or invalid data.
500 Internal Server Error: Connection failure.

Example:

curl -X POST https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app/sig

-H "Content-Type: application/json" \
-d '{"email":"[email protected]","password":"securepassword123","full

https://stackedit.io/app# 17/50
4/28/25, 1:06 PM StackEdit

Response:

{"message": "User registered successfully"}

5. Login User

Endpoint: /login

Method: POST

Description: Authenticates a user and updates their last_login_date .

Request Body (JSON):

{
"email": "[email protected]",
"password": "securepassword123"
}

Response:

200 OK: Login details with user information.

400 Bad Request: Incorrect password or user not found.
500 Internal Server Error: Connection failure.

Example:

curl -X POST https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app/log

-H "Content-Type: application/json" \
-d '{"email":"[email protected]","password":"securepassword123"}'

Response:

{
"message": "Login successful",
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"full_name": "John Doe",
"user_role": "customer",
"account_status": "active"

https://stackedit.io/app# 18/50
4/28/25, 1:06 PM StackEdit

6. Update User

Endpoint: /updateuser/<user_id>

Method: PATCH

Description: Partially updates a user’s data by user_id .

Parameters:

user_id (path, string): Unique user identifier (e.g., 123e4567-e89b-12d3-

a456-426614174000 ).

Request Body (JSON):

{
"full_name": "Jane Doe",
"email_verified": true
}

Response:

200 OK: Success message.

404 Not Found: User not found.
500 Internal Server Error: Connection failure.

Example:

curl -X PATCH https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app/up

-H "Content-Type: application/json" \
-d '{"full_name":"Jane Doe","email_verified":true}'

Response:

{"message": "User updated successfully"}

https://stackedit.io/app# 19/50
4/28/25, 1:06 PM StackEdit

7. Delete User by Full Name

Endpoint: /deleteuser/<full_name>

Method: DELETE

Description: Deletes a user by their full_name , accessible only to admins.

Parameters:

full_name (path, string): User’s full name (e.g., John Doe ).

Headers:

User-Role : Role of the requesting user ( admin ).

Response:

200 OK: Success message.

403 Forbidden: Invalid or missing role.
404 Not Found: User not found.
500 Internal Server Error: Connection failure.

Example:

curl -X DELETE -H "User-Role: admin" https://idx-mywebapi-34600209-e5q

Response:

{"message": "User 'John Doe' deleted successfully"}

Statistical Analysis

Endpoint Summary

The API includes 7 endpoints for user management with role-based access control.

https://stackedit.io/app# 20/50
4/28/25, 1:06 PM StackEdit

Distribution by HTTP Method

Method

Count

Percentage

Endpoints

GET

42.86%

/getusersbyall , /getusers , /getuser/<user_id>

POST

28.57%

/signup , /login

PATCH

14.29%

/updateuser/<user_id>

DELETE

14.29%

/deleteuser/<full_name>

Insight: GET endpoints are the most common (42.86%), reflecting frequent data
retrieval needs, followed by POST for user creation and authentication.

https://stackedit.io/app# 21/50
4/28/25, 1:06 PM StackEdit

Functionality Breakdown

Function

Count

Percentage

Endpoints

Read

42.86%

/getusersbyall , /getusers , /getuser/<user_id>

Create

14.29%

/signup

Update

14.29%

/updateuser/<user_id>

Delete

14.29%

/deleteuser/<full_name>

Authenticate

1
https://stackedit.io/app# 22/50
4/28/25, 1:06 PM StackEdit

14.29%

/login

Insight: Read operations dominate, with authentication and data modification evenly
distributed.

Response Status Codes

Status Code

Count

Endpoints

200 OK

All except /signup

201 Created

/signup

400 Bad Request

/signup , /login

403 Forbidden

/getusers , /getuser/<user_id> , /deleteuser/<full_name>

404 Not Found

/getuser/<user_id> , /updateuser/<user_id> , /deleteuser/<full_name>

https://stackedit.io/app# 23/50
4/28/25, 1:06 PM StackEdit

500 Internal Server Error

All endpoints

Insight: Robust error handling with role-based access (403) and resource-specific errors
(404).

Hypothetical Usage (1,000 Requests)

Endpoint

Requests

Percentage

Notes

/getusersbyall

200

20%

Public user browsing

/getusers

150

15%

Admin/travel agent queries

/getuser/<user_id>

150

15%

Specific user lookups

/signup

https://stackedit.io/app# 24/50
4/28/25, 1:06 PM StackEdit

200

20%

New user registrations

/login

250

25%

Frequent user logins

/updateuser/<user_id>

25

2.5%

Rare updates

/deleteuser/<full_name>

25

2.5%

Rare admin deletions

Insight: Authentication ( /login ) and registration ( /signup ) are the most frequent,
followed by read operations.

Testing Instructions

Using curl

Use the example commands provided for each endpoint.

Encode spaces in path parameters (e.g., John%20Doe ).
Include Content-Type: application/json for POST and PATCH requests.

https://stackedit.io/app# 25/50
4/28/25, 1:06 PM StackEdit

Add User-Role header for restricted endpoints.

Using Postman

1. Set the base URL: https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app .

2. Configure the HTTP method and endpoint.
3. Add headers ( User-Role ) and JSON body (for POST/PATCH) as needed.
4. Send requests and verify responses.

Using a Browser

Access GET endpoints directly (e.g., /getusersbyall ).

Example: https://idx-mywebapi-34600209-e5q6islzdq-
df.a.run.app/getusersbyall
Note: Restricted GET endpoints require headers, so use Postman or curl .

Best Practices

Security:
Store MongoDB credentials securely in environment variables.
Use HTTPS to protect sensitive data (e.g., passwords).
Implement JWT or session-based authentication for /login .
Error Handling: All endpoints include MongoDB connection checks and role-based
validation.
Scalability: Add pagination for /getusersbyall and /getusers to handle large
datasets.
Enhancements:
Add email verification for /signup .
Implement password reset functionality.
Allow role updates for admins via /updateuser/<user_id> .

Conclusion

https://stackedit.io/app# 26/50
4/28/25, 1:06 PM StackEdit

The User Operation API provides a secure and efficient interface for managing user
accounts, with role-based access control for sensitive operations. The statistical analysis
shows a balanced design, with 42.86% read operations and frequent
authentication/registration usage (45% of hypothetical requests). For production,
prioritize security enhancements and scalability optimizations.

Booking System API Documentation

This document outlines the RESTful API for managing booking operations, built with
Flask and MongoDB Atlas. The API supports creating, reading, updating, and deleting
bookings, as well as initiating checkout sessions and updating payment statuses. A
statistical analysis provides insights into the API’s structure and usage patterns.

Base URL

https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app

API Endpoints

1. List All Bookings

Endpoint: /getbookings

Method: GET

Description: Retrieves all bookings from the database.

Response:

200 OK: Array of booking objects.

https://stackedit.io/app# 27/50
4/28/25, 1:06 PM StackEdit

500 Internal Server Error: Connection failure.

Example:

curl https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app/getbookings

Response:

[
{
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"user_email": "[email protected]",
"tour_id": "T001",
"tour_destination": "Paris",
"tour_dates": "2025-06-01 to 2025-06-07",
"booking_status": "Pending",
"payment_status": "Unpaid",
"payment_amount": 1500.00,
"booking_reference": "BR123456"
}
]

2. Get Booking by User ID

Endpoint: /getbooking/<user_id>

Method: GET

Description: Retrieves a single booking by user_id .

Parameters:

user_id (path, string): Unique user identifier (e.g., 123e4567-e89b-12d3-

a456-426614174000 ).

Response:

200 OK: Booking object.

404 Not Found: Booking not found.
500 Internal Server Error: Connection failure.

https://stackedit.io/app# 28/50
4/28/25, 1:06 PM StackEdit

Example:

curl https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app/getbooking/

Response:

{
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"user_email": "[email protected]",
"tour_id": "T001",
"tour_destination": "Paris",
"tour_dates": "2025-06-01 to 2025-06-07",
"booking_status": "Pending",
"payment_status": "Unpaid",
"payment_amount": 1500.00,
"booking_reference": "BR123456"
}

3. Create Booking

Endpoint: /addbooking

Method: POST

Description: Creates a new booking.

Request Body (JSON):

{
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"user_email": "[email protected]",
"tour_id": "T001",
"tour_destination": "Paris",
"tour_dates": "2025-06-01 to 2025-06-07",
"booking_status": "Pending",
"payment_status": "Unpaid",
"payment_amount": 1500.00,
"booking_reference": "BR123456"
}

https://stackedit.io/app# 29/50
4/28/25, 1:06 PM StackEdit

Response:

201 Created: Success message with booking reference.

400 Bad Request: Missing required fields.
500 Internal Server Error: Connection failure.

Example:

curl -X POST https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app/add

-H "Content-Type: application/json" \
-d '{"user_id":"123e4567-e89b-12d3-a456-426614174000","user_email":"

Response:

{
"message": "Booking added successfully",
"booking_reference": "BR123456"
}

4. Delete Booking by Reference

Endpoint: /deletebooking/<booking_reference>

Method: DELETE

Description: Deletes a booking by its booking_reference .

Parameters:

booking_reference (path, string): Unique booking identifier (e.g.,

BR123456 ).

Response:

200 OK: Success message.

404 Not Found: Booking not found.
500 Internal Server Error: Connection failure.

Example:

https://stackedit.io/app# 30/50
4/28/25, 1:06 PM StackEdit

curl -X DELETE https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app/d

Response:

{
"message": "Booking with reference BR123456 deleted successfully"
}

5. Initiate Checkout Session

Endpoint: /checkout-session

Method: POST

Description: Initiates a checkout session for a booking.

Request Body (JSON):

{
"booking_reference": "BR123456"
}

Response:

200 OK: Checkout session details.

400 Bad Request: Missing booking reference or payment already completed.
404 Not Found: Booking not found.
500 Internal Server Error: Connection failure.

Example:

curl -X POST https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app/che

-H "Content-Type: application/json" \
-d '{"booking_reference":"BR123456"}'

Response:

https://stackedit.io/app# 31/50
4/28/25, 1:06 PM StackEdit

{
"booking_reference": "BR123456",
"payment_amount": 1500.00,
"currency": "USD",
"payment_status": "Initiated",
"payment_url": "https://payment-gateway.example.com/pay/BR123456"
}

6. Update Payment Status

Endpoint: /updatepayment/<booking_reference>

Method: PUT

Description: Updates the payment status to Paid and booking status to

Confirmed for a booking.

Parameters:

booking_reference (path, string): Unique booking identifier (e.g.,

BR123456 ).

Response:

200 OK: Success message.

400 Bad Request: Payment already marked as paid.
404 Not Found: Booking not found.
500 Internal Server Error: Connection failure.

Example:

curl -X PUT https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app/upda

Response:

{
"message": "Payment status updated to Paid for booking BR123456"
}

https://stackedit.io/app# 32/50
4/28/25, 1:06 PM StackEdit

Statistical Analysis

Endpoint Summary

The API includes 6 endpoints for managing bookings and payment processes.

Distribution by HTTP Method

Method

Count

Percentage

Endpoints

GET

33.33%

/getbookings , /getbooking/<user_id>

POST

33.33%

/addbooking , /checkout-session

PUT

16.67%

/updatepayment/<booking_reference>

DELETE
https://stackedit.io/app# 33/50
4/28/25, 1:06 PM StackEdit

16.67%

/deletebooking/<booking_reference>

Insight: Balanced distribution between read (GET) and write (POST, PUT, DELETE)
operations, reflecting diverse booking management needs.

Functionality Breakdown

Function

Count

Percentage

Endpoints

Read

33.33%

/getbookings , /getbooking/<user_id>

Create

16.67%

/addbooking

Delete

16.67%

/deletebooking/<booking_reference>

Payment

https://stackedit.io/app# 34/50
4/28/25, 1:06 PM StackEdit

33.33%

/checkout-session , /updatepayment/<booking_reference>

Insight: Equal focus on reading bookings and payment-related operations, with single
endpoints for creation and deletion.

Response Status Codes

Status Code

Count

Endpoints

200 OK

All except /addbooking

201 Created

/addbooking

400 Bad Request

/addbooking , /checkout-session , /updatepayment/<booking_reference>

404 Not Found

/getbooking/<user_id> , /deletebooking/<booking_reference> , /checkout-

session , /updatepayment/<booking_reference>

500 Internal Server Error

https://stackedit.io/app# 35/50
4/28/25, 1:06 PM StackEdit

All endpoints

Insight: Comprehensive error handling with specific validation (400) and resource errors
(404).

Hypothetical Usage (1,000 Requests)

Endpoint

Requests

Percentage

Notes

/getbookings

250

25%

Admin viewing all bookings

/getbooking/<user_id>

200

20%

User-specific booking queries

/addbooking

200

20%

New bookings

/deletebooking/<booking_reference>

50

https://stackedit.io/app# 36/50
4/28/25, 1:06 PM StackEdit

5%

Booking cancellations

/checkout-session

200

20%

Payment initiations

/updatepayment/<booking_reference>

100

10%

Payment confirmations

Insight: Read and payment-related endpoints dominate (65%), with booking creation
also significant.

Testing Instructions

Using curl

Execute the example commands provided for each endpoint.

Encode spaces in path parameters (e.g., BR123456 does not require encoding).
Include Content-Type: application/json for POST requests.

Using Postman

1. Set the base URL: https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app .

2. Configure the HTTP method and endpoint.
3. Add JSON body for POST requests under the Body tab (raw, JSON).
4. Send requests and verify responses.

https://stackedit.io/app# 37/50
4/28/25, 1:06 PM StackEdit

Using a Browser

Access GET endpoints directly (e.g., /getbookings ).

Example: https://idx-mywebapi-34600209-e5q6islzdq-
df.a.run.app/getbookings
Note: POST, PUT, and DELETE endpoints require tools like Postman or curl .

Best Practices

Security:
Store MongoDB credentials in environment variables.
Implement authentication to restrict /addbooking ,
/deletebooking/<booking_reference> , and
/updatepayment/<booking_reference> to authorized users.
Use HTTPS to protect sensitive data (e.g., payment details).
Error Handling: All endpoints include MongoDB connection checks and
appropriate status codes.
Scalability: Add pagination for /getbookings to handle large datasets.
Enhancements:
Integrate a real payment gateway (e.g., Stripe) for /checkout-session .
Add validation for tour_id and user_id against the Tour and User
collections.
Implement booking status transitions (e.g., Pending to Cancelled ).

Code Improvement Recommendations

Use jsonify : Replace json.dumps with jsonify for consistent Flask JSON
responses (e.g., in read_bookings , read_booking_by_user_id , etc.).
Authentication: Add role-based access control for sensitive endpoints (e.g.,
/deletebooking/<booking_reference> ).
Validation: Ensure booking_reference is unique in /addbooking to prevent
duplicates.

https://stackedit.io/app# 38/50
4/28/25, 1:06 PM StackEdit

Conclusion

The Booking System API provides a robust interface for managing travel bookings and
payments, with a balanced focus on read (33.33%) and payment-related operations
(33.33%). The statistical analysis highlights frequent usage of read and payment
endpoints (65% of hypothetical requests). For production, prioritize security, payment
gateway integration, and scalability enhancements.

Reviews System API Documentation

This document outlines the RESTful API for managing review operations, built with Flask
and MongoDB Atlas. The API supports creating, reading, updating, and deleting reviews
for travel tours. A statistical analysis provides insights into the API’s structure and usage
patterns.

Base URL

https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app

API Endpoints

1. List All Reviews

Endpoint: /getreviews

Method: GET

Description: Retrieves all reviews from the database.

https://stackedit.io/app# 39/50
4/28/25, 1:06 PM StackEdit

Response:

200 OK: Array of review objects.

500 Internal Server Error: Connection failure.

Example:

curl https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app/getreviews

Response:

[
{
"review_id": "R001",
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"user_email": "[email protected]",
"tour_id": "T001",
"tour_destination": "Paris",
"rating": 5,
"review_text": "Amazing experience!",
"review_date": "2025-04-28T10:00:00Z"
}
]

2. Get Reviews by User ID

Endpoint: /getreviewsbyuser/<user_id>

Method: GET

Description: Retrieves all reviews submitted by a specific user.

Parameters:

user_id (path, string): Unique user identifier (e.g., 123e4567-e89b-12d3-

a456-426614174000 ).

Response:

200 OK: Array of review objects.

500 Internal Server Error: Connection failure.
https://stackedit.io/app# 40/50
4/28/25, 1:06 PM StackEdit

Example:

curl https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app/getreviewsb

Response:

[
{
"review_id": "R001",
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"user_email": "[email protected]",
"tour_id": "T001",
"tour_destination": "Paris",
"rating": 5,
"review_text": "Amazing experience!",
"review_date": "2025-04-28T10:00:00Z"
}
]

3. Create Review

Endpoint: /addreview

Method: POST

Description: Adds a new review to the database.

Request Body (JSON):

{
"review_id": "R002",
"user_id": "123e4567-e89b-12d3-a456-426614174000",
"user_email": "[email protected]",
"tour_id": "T001",
"tour_destination": "Paris",
"rating": 4,
"review_text": "Great tour, highly recommend!",
"review_date": "2025-04-28T12:00:00Z"
}

https://stackedit.io/app# 41/50
4/28/25, 1:06 PM StackEdit

Response:

201 Created: Success message.

500 Internal Server Error: Connection failure.

Example:

curl -X POST https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app/add

-H "Content-Type: application/json" \
-d '{"review_id":"R002","user_id":"123e4567-e89b-12d3-a456-426614174

Response:

{"message": "Review added successfully"}

4. Update Review

Endpoint: /updatereview/<review_id>

Method: PATCH

Description: Updates the rating and/or review_text of a review by

review_id .

Parameters:

review_id (path, string): Unique review identifier (e.g., R001 ).

Request Body (JSON):

{
"rating": 3,
"review_text": "Good tour, but could be improved."
}

Response:

200 OK: Success message.

400 Bad Request: No valid fields provided.
https://stackedit.io/app# 42/50
4/28/25, 1:06 PM StackEdit

404 Not Found: Review not found.

500 Internal Server Error: Connection failure.

Example:

curl -X PATCH https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app/up

-H "Content-Type: application/json" \
-d '{"rating":3,"review_text":"Good tour, but could be improved."}'

Response:

{"message": "Review updated successfully"}

5. Delete Review

Endpoint: /deletereview/<review_id>

Method: DELETE

Description: Deletes a review by its review_id .

Parameters:

review_id (path, string): Unique review identifier (e.g., R001 ).

Response:

200 OK: Success message.

404 Not Found: Review not found.
500 Internal Server Error: Connection failure.

Example:

curl -X DELETE https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app/d

Response:

https://stackedit.io/app# 43/50
4/28/25, 1:06 PM StackEdit

{"message": "Review deleted successfully"}

Statistical Analysis

Endpoint Summary

The API includes 5 endpoints for managing reviews.

Distribution by HTTP Method

Method

Count

Percentage

Endpoints

GET

40.00%

/getreviews , /getreviewsbyuser/<user_id>

POST

20.00%

/addreview

PATCH

20.00%
https://stackedit.io/app# 44/50
4/28/25, 1:06 PM StackEdit

/updatereview/<review_id>

DELETE

20.00%

/deletereview/<review_id>

Insight: GET endpoints are the most common (40%), reflecting frequent review retrieval,
with balanced support for creation, update, and deletion.

Functionality Breakdown

Function

Count

Percentage

Endpoints

Read

40.00%

/getreviews , /getreviewsbyuser/<user_id>

Create

20.00%

/addreview

Update

20.00%

https://stackedit.io/app# 45/50
4/28/25, 1:06 PM StackEdit

/updatereview/<review_id>

Delete

20.00%

/deletereview/<review_id>

Insight: Read operations dominate, aligning with typical review system usage where
viewing reviews is more frequent than modification.

Response Status Codes

Status Code

Count

Endpoints

200 OK

All except /addreview

201 Created

/addreview

400 Bad Request

/updatereview/<review_id>

404 Not Found

/updatereview/<review_id> , /deletereview/<review_id>

https://stackedit.io/app# 46/50
4/28/25, 1:06 PM StackEdit

500 Internal Server Error

All endpoints

Insight: Robust error handling with specific validation (400) and resource errors (404) for
update and delete operations.

Hypothetical Usage (1,000 Requests)

Endpoint

Requests

Percentage

Notes

/getreviews

400

40%

Public review browsing

/getreviewsbyuser/<user_id>

300

30%

User-specific review queries

/addreview

150

15%

New review submissions

/updatereview/<review_id>

https://stackedit.io/app# 47/50
4/28/25, 1:06 PM StackEdit

50

5%

Review edits

/deletereview/<review_id>

50

5%

Review deletions

Insight: Read operations dominate (70%), reflecting typical review system usage, with
review creation being moderately frequent.

Testing Instructions

Using curl

Execute the example commands provided for each endpoint.

Encode spaces in path parameters if needed (e.g., R001 does not require
encoding).
Include Content-Type: application/json for POST and PATCH requests.

Using Postman

1. Set the base URL: https://idx-mywebapi-34600209-e5q6islzdq-df.a.run.app .

2. Configure the HTTP method and endpoint.
3. Add JSON body for POST and PATCH requests under the Body tab (raw, JSON).
4. Send requests and verify responses.

Using a Browser

Access GET endpoints directly (e.g., /getreviews ).

https://stackedit.io/app# 48/50
4/28/25, 1:06 PM StackEdit

Example: https://idx-mywebapi-34600209-e5q6islzdq-
df.a.run.app/getreviews
Note: POST, PATCH, and DELETE endpoints require tools like Postman or curl .

Best Practices

Security:
Store MongoDB credentials in environment variables.
Implement authentication to restrict /addreview ,
/updatereview/<review_id> , and /deletereview/<review_id> to
authenticated users.
Ensure only the review owner or admins can update/delete reviews.
Use HTTPS to protect sensitive data (e.g., user email).
Error Handling: All endpoints include MongoDB connection checks and
appropriate status codes.
Scalability: Add pagination for /getreviews to handle large datasets.
Enhancements:
Validate user_id and tour_id against the User and Tour collections in
/addreview .
Add input validation for rating (e.g., 1-5) in /addreview and
/updatereview/<review_id> .
Implement a review moderation system for /addreview .

Code Improvement Recommendations

Use jsonify : Replace json.dumps with jsonify for consistent Flask JSON
responses (e.g., in read_reviews , get_reviews_byuser , etc.).
Input Validation: Add checks for required fields and valid data types in
/addreview (e.g., rating between 1-5, unique review_id ).
Authentication: Implement role-based access control to ensure only
authenticated users can create, update, or delete reviews.
Error Handling: Standardize error responses (e.g., get_reviews_byuser returns a
string "Connection Problem" instead of JSON).

https://stackedit.io/app# 49/50
4/28/25, 1:06 PM StackEdit

Review Date: Auto-generate review_date in /addreview using

datetime.datetime.utcnow().isoformat() instead of requiring it in the request.

Conclusion

The Reviews System API provides an efficient interface for managing tour reviews, with
a strong focus on read operations (40% of endpoints). The statistical analysis highlights
frequent review retrieval (70% of hypothetical requests) and moderate creation activity.
For production, prioritize security, input validation, and scalability enhancements to
ensure a robust review system.

https://stackedit.io/app# 50/50