📈 Stock Trading API

A simple Flask REST API for managing stock trades - perfect for learning functional testing!

⚠️ Disclaimer: This is an example application for educational purposes only. It is not production-ready. Never hardcode credentials or API keys in real applications - use environment variables or a secrets manager instead.

📝 Exercise: Ready to write your own tests? Check out the Functional Test Exercise!

Prerequisites

• Python 3.7 or higher
• pip (Python package installer)

See the Installation Guide for detailed instructions on installing Python and pip.

Installation

pip install -r requirements.txt

Run

python app.py

The API runs at http://127.0.0.1:5000

Postman Collection

Import stock-trading-api.postman_collection.json into Postman to explore the API endpoints.

The collection includes two variables pre-configured:

• base_url - set to http://127.0.0.1:5000
• api_key - set to test-key-123

Importing the Collection

1. Download and install Postman
2. Open Postman
3. Click Import in the top left corner
4. Select File and choose stock-trading-api.postman_collection.json
5. Click Import to confirm

The collection will appear in your Collections sidebar, ready to use.

For more details see the official Postman import guide.

Authentication

Most endpoints require an API key. Include it in the X-API-Key header.

Valid API Keys:

• test-key-123
• demo-key-456

API Endpoints

Get all stocks (no auth required)

GET /stocks

Get a specific stock (no auth required)

GET /stocks/{symbol}

Get all trades (requires auth)

GET /trades
X-API-Key: test-key-123

Get a specific trade (requires auth)

GET /trades/{id}
X-API-Key: test-key-123

Execute a trade (requires auth)

POST /trades
X-API-Key: test-key-123
Content-Type: application/json

{
  "symbol": "AAPL",
  "quantity": 10,
  "action": "buy"
}

Update a trade (requires auth)

PUT /trades/{id}
X-API-Key: test-key-123
Content-Type: application/json

{
  "quantity": 15
}

Cancel a trade (requires auth)

DELETE /trades/{id}
X-API-Key: test-key-123

Get portfolio (requires auth)

GET /portfolio
X-API-Key: test-key-123

Get portfolio value (requires auth)

GET /portfolio/value
X-API-Key: test-key-123

Get account balance (requires auth)

GET /account/balance
X-API-Key: test-key-123

Deposit funds (requires auth)

POST /account/deposit
X-API-Key: test-key-123
Content-Type: application/json

{
  "amount": 1000.00
}

Withdraw funds (requires auth)

POST /account/withdraw
X-API-Key: test-key-123
Content-Type: application/json

{
  "amount": 500.00
}

Example Usage

# Get all available stocks (no auth)
curl http://127.0.0.1:5000/stocks

# Get specific stock (no auth)
curl http://127.0.0.1:5000/stocks/AAPL

# Deposit funds (with auth)
curl -X POST http://127.0.0.1:5000/account/deposit \
  -H "Content-Type: application/json" \
  -H "X-API-Key: test-key-123" \
  -d '{"amount":10000}'

# Execute a buy trade (with auth)
curl -X POST http://127.0.0.1:5000/trades \
  -H "Content-Type: application/json" \
  -H "X-API-Key: test-key-123" \
  -d '{"symbol":"AAPL","quantity":10,"action":"buy"}'

# Get all trades (with auth)
curl -H "X-API-Key: test-key-123" http://127.0.0.1:5000/trades

# Update a trade (with auth)
curl -X PUT http://127.0.0.1:5000/trades/1 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: test-key-123" \
  -d '{"quantity":15}'

# Get portfolio (with auth)
curl -H "X-API-Key: test-key-123" http://127.0.0.1:5000/portfolio

# Get portfolio value (with auth)
curl -H "X-API-Key: test-key-123" http://127.0.0.1:5000/portfolio/value

# Get account balance (with auth)
curl -H "X-API-Key: test-key-123" http://127.0.0.1:5000/account/balance

# Cancel a trade (with auth)
curl -X DELETE -H "X-API-Key: test-key-123" http://127.0.0.1:5000/trades/1

Running Tests

# Install test dependencies
pip install -r requirements.txt

# Run unit tests (no server needed)
pytest tests/unit/ -v

# Run functional tests (requires running server)
# Start the API server (in one terminal)
python app.py

# Run tests (in another terminal)
pytest tests/functional/ -v

# Run all tests
pytest tests/ -v

# Run tests by marker
pytest -m unit -v
pytest -m functional -v
pytest -m positive -v
pytest -m negative -v