Bookshelf API — New Postman Git-Native Demo

A Flask REST API for managing books, built to demonstrate the new Postman's git-native workflow — where API collections live as YAML files in your repo, right next to your code.

What This Demonstrates

The new Postman introduced Collections as Code. Instead of API collections living in Postman's cloud as opaque JSON blobs, they now live as readable YAML files in your Git repository:

postman/
├── collections/
│   └── Bookshelf API/
│       ├── .resources/definition.yaml       # Collection metadata
│       ├── Health/
│       │   └── Health Check.request.yaml    # Individual request + tests
│       └── Books/
│           ├── List All Books.request.yaml
│           ├── Create Book.request.yaml
│           ├── Get Book by ID.request.yaml
│           ├── Update Book.request.yaml
│           ├── Delete Book.request.yaml
│           ├── Search Books.request.yaml
│           ├── Filter Books by Genre.request.yaml
│           └── Get Deleted Book (404).request.yaml
├── environments/
│   ├── Bookshelf API - Local.environment.yaml
│   └── Bookshelf API - CI.environment.yaml
└── globals/
    └── workspace.globals.yaml

Each request is its own .request.yaml file with embedded test scripts. Editing a request in Postman writes directly to these files.

Why This Matters

Before	Now (New Postman)
Collections stored in Postman's cloud	Collections stored as YAML files in your repo
Exported as massive, unreadable JSON	Each request is a small, readable YAML file
API changes invisible in code reviews	API changes show up as clean diffs in PRs
Tests had to be rewritten for CI	Same collection file runs in Postman, pre-commit hooks, and GitHub Actions
Collections drifted from actual code	Collections live next to the code — single source of truth

The Git-Native Workflow

1. Edit a request or test in Postman's Local View
2. Save — Postman writes the change to the YAML file on disk
3. git diff — see a clean, readable diff of exactly what changed
4. git commit && git push — API changes ship in the same PR as code changes
5. CI runs — GitHub Actions runs the same collection with postman collection run

Getting Started

Prerequisites

• uv (Python package manager)
• The new Postman

Run the API

uv sync
uv run flask --app src.bookshelf_api.run:app run --debug

The API runs at http://localhost:5000.

Connect to Postman

1. Open the new Postman and create a workspace
2. Connect the workspace to this local folder via Native Git
3. Postman reads the postman/ folder and loads the collection + environments
4. Select the Local environment and run the collection

Run Tests

# Unit tests
uv run pytest -v

# Lint
uv run ruff check src/ tests/

# Type check
uv run mypy src/

API Endpoints

Method	Endpoint	Description
GET	/health	Health check
GET	/api/books	List all books (optional ?genre= filter)
GET	/api/books/search?q=	Search by title or author
GET	/api/books/<id>	Get a book by ID
POST	/api/books	Create a book
PATCH	/api/books/<id>	Update a book
DELETE	/api/books/<id>	Delete a book

CI Pipeline

The included GitHub Actions workflow (.github/workflows/ci.yml) runs:

1. Lint + type check + unit tests with uv
2. Postman collection tests using the Postman CLI against the same YAML files