Skip to content

[FEATURE] Replace Postman collection with .rest file #493

@nanotaboada

Description

@nanotaboada

Problem

The repository includes a Postman collection for testing the API endpoints. This creates
several friction points:

  • Vendor lock-in: Postman is a proprietary tool that requires account sign-in and a
    separate desktop app (or browser extension) to use.
  • Redundant with Swagger: The API already exposes interactive documentation at /docs
    (Swagger UI), which covers ad-hoc exploration without any additional tooling.
  • Not editor-native: The collection lives outside the development workflow. Developers
    have to context-switch to Postman instead of staying in their editor.
  • Format opacity: The .json collection format is not human-readable at a glance and
    is not diff-friendly in code review.

Proposed Solution

Replace postman_collections/ with a rest/players.rest file using the plain-text
HTTP file format,
supported natively by:

  • VS Code via the REST Client extension (humao.rest-client)
  • IntelliJ IDEA / WebStorm via the built-in HTTP Client

The file is plain text, version-controlled, diff-friendly, and runs directly inside the
editor without leaving the development environment.

Suggested Approach

  • Remove postman_collections/
  • Add rest/players.rest covering all CRUD operations, with request bodies aligned with
    test fixtures (natural key lookups where needed)
  • Add humao.rest-client to .vscode/extensions.json recommendations
  • Update Black, Codecov, and flake8 exclusion lists: remove postman_collections/, add
    rest/
  • Add an "HTTP Requests" section to README.md
  • Update CHANGELOG.md

Acceptance Criteria

  • postman_collections/ is removed from the repository
  • rest/players.rest covers: health check, POST, GET all, GET by UUID, GET by squad
    number, PUT, DELETE (with two-step UUID resolution for runtime-generated IDs)
  • Request bodies and UUIDs in rest/players.rest are aligned with test fixtures
  • humao.rest-client is listed in .vscode/extensions.json
  • All exclusion lists (Black, Codecov, flake8) updated
  • README.md references rest/players.rest and the REST Client extension
  • All pre-commit checks pass (flake8, black --check, pytest, coverage ≥ 80%)

References

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestpythonPull requests that update Python code

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions