Merge pull request #494 from nanotaboada/chore/rest-client

[FEATURE] Replace Postman collection with `.rest` file

Author: nanotaboada

.vscode/extensions.json

@@ -30,6 +30,9 @@
     "ms-azuretools.vscode-containers",   // Container Tools - Docker and container management
     "yy0931.vscode-sqlite3-editor",      // SQLite3 Editor - View and edit SQLite databases
 
+    // API Development
+    "humao.rest-client",                 // REST Client - Send HTTP requests from .http files
+
     // UI Enhancements
     "github.github-vscode-theme",        // GitHub Theme - GitHub color themes
     "pkief.material-icon-theme",         // Material Icon Theme - Material Design file icons

.vscode/settings.json

@@ -34,7 +34,7 @@
     "**/.vscode/**",
     "**/assets/**",
     "**/htmlcov/**",
-    "**/postman_collections/**",
+    "**/rest/**",
     "**/scripts/**",
     "**/tools/**",
     "**/storage/**",

CHANGELOG.md

@@ -44,6 +44,8 @@ This project uses famous football coaches as release codenames, following an A-Z
 
 ### Added
 
+- `rest/players.rest` file covering all CRUD operations, compatible with the VS Code REST Client extension (#493)
+- `humao.rest-client` added to `.vscode/extensions.json` recommendations (#493)
 - UUID v4 primary key for the `players` table, replacing the previous integer PK (#66)
 - `PlayerRequestModel` Pydantic model for POST/PUT request bodies (no `id` field) (#66)
 - `PlayerResponseModel` Pydantic model for GET/POST response bodies (includes `id: UUID`) (#66)
@@ -69,6 +71,8 @@ This project uses famous football coaches as release codenames, following an A-Z
 
 ### Removed
 
+- `postman_collections/` directory replaced by `rest/players.rest` (#493)
+
 ### Fixed
 
 - POST/PUT/DELETE routes now raise `HTTP 500` on DB failure instead of silently returning success (#66)

README.md

@@ -58,6 +58,10 @@ http://localhost:9000/docs
 
 ![API Documentation](assets/images/swagger.png)
 
+## HTTP Requests
+
+The [`rest/players.rest`](rest/players.rest) file covers all CRUD operations and can be run directly in VS Code with the [REST Client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) extension.
+
 ## Container
 
 ### Docker Compose

codecov.yml

@@ -2,7 +2,7 @@
 # https://docs.codecov.com/docs/codecov-yaml
 
 coverage:
-# https://docs.codecov.com/docs/commit-status
+  # https://docs.codecov.com/docs/commit-status
   status:
     project:
       default:
@@ -42,7 +42,7 @@ ignore:
   - "^assets/.*"
   - "^databases/.*"
   - "^models/.*"
-  - "^postman_collections/.*"
+  - "^rest/.*"
   - "^schemas/.*"
   - "^tools/.*"
   - "^tests/.*"

postman_collections/python-samples-fastapi-restful.postman_collection.json

@@ -11,7 +11,7 @@ exclude = '''
   | \.vscode
   | assets
   | htmlcov
-  | postman_collections
+  | rest
   | scripts
   | tools
   | storage

pyproject.toml

@@ -0,0 +1,104 @@
+### RESTful API with Python 3 and FastAPI
+### https://github.com/nanotaboada/python-samples-fastapi-restful
+###
+### Requires the REST Client extension for VS Code:
+### https://marketplace.visualstudio.com/items?itemName=humao.rest-client
+###
+### Key design note:
+###   squad_number = natural key  (domain-meaningful, preferred for lookups)
+###   id (UUID)    = surrogate key (internal, opaque, used for CRUD operations)
+
+@baseUrl = http://localhost:9000
+
+# ------------------------------------------------------------------------------
+# Health
+# ------------------------------------------------------------------------------
+
+### GET /health/ — liveness check
+GET {{baseUrl}}/health/
+Accept: application/json
+
+# ------------------------------------------------------------------------------
+# POST /players/ — Create
+# Thiago Almada (squad 16): not seeded in the database, used as the creation
+# fixture. No id in the body; the server generates a UUID v4 on creation.
+# ------------------------------------------------------------------------------
+
+### POST /players/ — Create a new Player
+POST {{baseUrl}}/players/
+Content-Type: application/json
+
+{
+  "firstName": "Thiago",
+  "middleName": "Ezequiel",
+  "lastName": "Almada",
+  "dateOfBirth": "2001-04-26T00:00:00.000Z",
+  "squadNumber": 16,
+  "position": "Attacking Midfield",
+  "abbrPosition": "AM",
+  "team": "Atlanta United FC",
+  "league": "Major League Soccer",
+  "starting11": false
+}
+
+# ------------------------------------------------------------------------------
+# GET /players/ — Retrieve all
+# ------------------------------------------------------------------------------
+
+### GET /players/ — Retrieve all Players
+GET {{baseUrl}}/players/
+Accept: application/json
+
+# ------------------------------------------------------------------------------
+# GET /players/{player_id} — Retrieve by UUID (surrogate key, internal)
+# Emiliano Martínez (squad 23): UUID v5, seeded by seed_001.
+# ------------------------------------------------------------------------------
+
+### GET /players/{player_id} — Retrieve a Player by UUID
+GET {{baseUrl}}/players/b04965e6-a9bb-591f-8f8a-1adcb2c8dc39
+Accept: application/json
+
+# ------------------------------------------------------------------------------
+# GET /players/squadnumber/{squad_number} — Retrieve by Squad Number (natural key, domain)
+# Preferred lookup for external consumers.
+# ------------------------------------------------------------------------------
+
+### GET /players/squadnumber/{squad_number} — Retrieve a Player by Squad Number
+GET {{baseUrl}}/players/squadnumber/10
+Accept: application/json
+
+# ------------------------------------------------------------------------------
+# PUT /players/{player_id} — Update
+# Emiliano Martínez (squad 23): UUID v5, seeded by seed_001.
+# ------------------------------------------------------------------------------
+
+### PUT /players/{player_id} — Update an existing Player
+PUT {{baseUrl}}/players/b04965e6-a9bb-591f-8f8a-1adcb2c8dc39
+Content-Type: application/json
+
+{
+  "firstName": "Emiliano",
+  "middleName": null,
+  "lastName": "Martínez",
+  "dateOfBirth": "1992-09-02T00:00:00.000Z",
+  "squadNumber": 23,
+  "position": "Goalkeeper",
+  "abbrPosition": "GK",
+  "team": "Aston Villa FC",
+  "league": "Premier League",
+  "starting11": true
+}
+
+# ------------------------------------------------------------------------------
+# DELETE /players/{player_id} — Delete
+# Thiago Almada (squad 16): created by POST above. Since the UUID is generated
+# at runtime, retrieve it first via squad number, then substitute it below.
+# ------------------------------------------------------------------------------
+
+### Step 1 — Look up Almada's UUID by squad number
+GET {{baseUrl}}/players/squadnumber/16
+Accept: application/json
+
+### Step 2 — Delete Almada using the UUID returned above
+# Replace {player_id} with the id field from the response above.
+DELETE {{baseUrl}}/players/{player_id}