FastAPI_Example.py

Explanation of New Features

1. Path and Query Parameter Metadata: Added descriptions and constraints for better validation and autogenerated documentation.
2. Nested Models: Demonstrated hierarchical data validation with the User model that includes a list of Item instances.
3. Partial Updates: Introduced a PATCH endpoint to allow partial updates of fields using the Body method.
4. Static Data: Provided a status endpoint that returns static information about the API.
5. Returning Key-Value Data: Added a summary endpoint to showcase mock data.

Main

What the Script Does

1. Starts the FastAPI Application
   When you run the script, it starts a web server using Uvicorn. This makes your FastAPI app accessible via the browser or API clients like Postman.

2. Default Endpoint (GET /)
   The browser sends a GET request to the root path (http://127.0.0.1:8000/).
   The root route (@app.get("/")) is defined in the script to return:

   {"message": "Welcome to the expanded FastAPI example!"}

   This is why you see that message in the browser or the API response.

3. 404 for /favicon.ico
   The browser automatically tries to load a favicon (a small icon displayed in the browser tab). Since no favicon is defined in the script, a 404 Not Found is returned, which is normal behavior.

---

What the Script Offers Beyond the Root Endpoint

The script defines several API endpoints that are not automatically accessed unless you explicitly call them. Here’s a summary of the key routes:

Endpoint	HTTP Method	Description
/	GET	Returns a welcome message.
/items/{item_id}	GET	Fetches an item by its item_id, with an optional query parameter.
/search/	GET	Searches items using limit and offset query parameters for pagination.
/items/	POST	Creates a new item using the Item model for validation.
/items/{item_id}	PUT	Updates an item by its item_id with a new Item object.
/items/{item_id}	DELETE	Deletes an item by its item_id.
/users/	POST	Creates a new user with optional nested items using the User model.
/items/{item_id}	PATCH	Partially updates fields (like price or on_offer) of an item by its ID.
/status/	GET	Returns static data, such as the API’s status and version.
/summary/	GET	Returns a dictionary with some mock data, such as total items and users.

---

Testing the Script

You need to explicitly visit or call other endpoints to explore more features of the script. For example:

1. ==Accessing the Swagger UI Go to http://127.0.0.1:8000/docs in your browser.==
   This interactive interface shows all the available endpoints and lets you test them directly.

2. Calling Specific Endpoints You can call the endpoints via:

   • Browser (e.g., http://127.0.0.1:8000/items/123?q=test).
   • API Clients like Postman or Curl.

---

Why You See Only the Welcome Message

You’ve accessed only the root endpoint (/). The other features of the script (like creating, updating, or searching for items) require you to call the respective endpoints explicitly.

Calling endpoints

Here’s how to call the respective endpoints of the script using various tools like browser, Curl, or Postman. Each example demonstrates an endpoint and its purpose.

1. Welcome Endpoint (GET /)

• Purpose: Displays a welcome message.
• Call:
  • Browser: Open http://127.0.0.1:8000/.
  • Curl:

    curl -X GET http://127.0.0.1:8000/

  • Response:

    {"message": "Welcome to the expanded FastAPI example!"}

2. Retrieve an Item (GET /items/{item_id})

• Purpose: Fetches item details by its item_id with an optional query parameter q.
• Example: Retrieve item 3 with query test.
• Call:

  • Browser: Open http://127.0.0.1:8000/items/3?q=test.

  • Curl:

    curl -X GET "http://127.0.0.1:8000/items/3?q=test"

  • Response:

    {"item_id": 3, "query": "test"}

---

3. Search Items (GET /search/)

• Purpose: Uses limit and offset query parameters for pagination.
• Example: Limit results to 5, skip the first 2.
• Call:
  • Browser: Open http://127.0.0.1:8000/search/?limit=5&offset=2.
  • Curl:

    curl -X GET "http://127.0.0.1:8000/search/?limit=5&offset=2"

  • Response:

    {"limit": 5, "offset": 2}

4. Create an Item (POST /items/)

• Purpose: Adds a new item.
• Example: Create an item named “Laptop” priced at 999.99.
• Call:
  • Curl:

curl -X POST “http://127.0.0.1:8000/items/” -H “Content-Type: application/json” -d ”{“name”: “Laptop”, “price”: 999.99, “description”: “High-end laptop”, “on_offer”: true}” - **Response:** json { “message”: “Item created successfully”, “item”: { “name”: “Laptop”, “price”: 999.99, “description”: “High-end laptop”, “on_offer”: true } } ```

5. Update an Item (PUT /items/{item_id})

• Purpose: Updates item details by its item_id.
• Example: Update item 3 with new data.
• Call:

  • Curl:

    curl -X PUT "http://127.0.0.1:8000/items/3" \
    -H "Content-Type: application/json" \
    -d '{"name": "Smartphone", "price": 499.99, "description": "Updated phone", "on_offer": false}'

  • Response:

    {
      "item_id": 3,
      "updated_item": {
        "name": "Smartphone",
        "price": 499.99,
        "description": "Updated phone",
        "on_offer": false
      }
    }

6. Delete an Item (DELETE /items/{item_id})

• Purpose: Deletes an item by its item_id.
• Example: Delete item 2.
• Call:

  • Curl:

    curl -X DELETE http://127.0.0.1:8000/items/2

  • Response:

    {"message": "Item 2 deleted successfully"}

---

7. Create a User (POST /users/)

• Purpose: Creates a user, optionally with nested items.
• Example: Create a user with items.
• Call:

  • Curl:

    curl -X POST "http://127.0.0.1:8000/users/" -H "Content-Type: application/json" -d "{\"username\": \"john_doe\", \"email\": \"john@example.com\", \"full_name\": \"John Doe\", \"items\": [{\"name\": \"Tablet\", \"price\": 299.99, \"description\": \"Portable tablet\"}]}"

  • Response:

    {
      "message": "User created successfully",
      "user": {
        "username": "john_doe",
        "email": "john@example.com",
        "full_name": "John Doe",
        "items": [
          {
            "name": "Tablet",
            "price": 299.99,
            "description": "Portable tablet",
            "on_offer": null
          }
        ]
      }
    }

8. Partially Update an Item (PATCH /items/{item_id})

• Purpose: Partially updates an item using optional fields.
• Example: Update the price of item 5.
• Call:

  • Curl:

    curl -X PATCH "http://127.0.0.1:8000/items/5" \
    -H "Content-Type: application/json" \
    -d '{"price": 79.99}'

  • Response:

    {
      "item_id": 5,
      "updates": {
        "price": 79.99
      }
    }

9. Check API Status (GET /status/)

• Purpose: Returns static information like API status.
• Call:

  • Browser: Open http://127.0.0.1:8000/status/.

  • Curl:

    curl -X GET http://127.0.0.1:8000/status/

  • Response:

    {"status": "API is running", "version": "1.0.0"}

10. Retrieve a Summary (GET /summary/)

• Purpose: Returns a mock summary of items and users.
• Call:

  • Browser: Open http://127.0.0.1:8000/summary/.

  • Curl:

    curl -X GET http://127.0.0.1:8000/summary/

  • Response:

    {"total_items": 42, "total_users": 5, "recent_activity": "Item purchase"}

---

Testing Tips

• Use Swagger UI at http://127.0.0.1:8000/docs for interactive testing of all endpoints.
• Use Postman for testing more complex requests with nested data.

New

Explanation of Changes:

• created_items: Items that have been created using the /items/ POST endpoint.
• updated_items: Items that have been updated using the /items/{item_id} PUT endpoint.
• deleted_items: Items that have been deleted using the /items/{item_id} DELETE endpoint.
• Summary Endpoint:
  • Returns counts of items created (created_items_count), updated (updated_items_count), and deleted (deleted_items_count).

---

Here’s the formatted content for use in cmd:

TEST LATER

Testing with curl:

1. Create an item:

   curl -X POST "http://127.0.0.1:8000/items/" -H "Content-Type: application/json" -d '{"name": "Tablet", "price": 299.99, "description": "Portable tablet"}'

2. Update an item:

   curl -X PUT "http://127.0.0.1:8000/items/1" \
   -H "Content-Type: application/json" \
   -d '{"name": "Tablet", "price": 250.00, "description": "Updated portable tablet"}'

3. Delete an item:

   curl -X DELETE "http://127.0.0.1:8000/items/1"

4. Get the summary:

   curl -X GET "http://127.0.0.1:8000/summary/"

Expected Response:

{
  "total_items": 0,
  "total_users": 5,
  "recent_activity": "Item purchase",
  "created_items_count": 1,
  "updated_items_count": 1,
  "deleted_items_count": 1
}

You can copy and paste these commands directly into cmd to test the API.

Note:

Make sure your FastAPI server is running on http://127.0.0.1:8000 before executing these commands.