[Q2-P1] Add contract tests to validate API assumptions #25
Description
Problem
SDK makes assumptions about API:
- Endpoints exist
- Response format matches expectations
- Field names are correct
Risk: Backend changes can break SDK
Solution
Add contract tests that validate SDK assumptions against API:
# tests/contract/test_api_contracts.py
class TestHistoricalEndpointContract:
"""Validate historical endpoint contract."""
def test_past_year_endpoint_exists(self):
response = requests.get(f'{API_URL}/v1/prices/past_year')
assert response.status_code != 404
def test_response_schema_matches_sdk(self):
response = requests.get(
f'{API_URL}/v1/prices/past_year',
params={'commodity': 'WTI_USD'},
headers={'Authorization': f'Token {TEST_KEY}'}
)
data = response.json()
# Validate structure
assert 'data' in data
assert 'prices' in data['data']
# Validate price schema
price = data['data']['prices'][0]
assert 'code' in price
assert 'price' in price
assert 'created_at' in price
assert 'type' in price
assert 'unit' in price
def test_pagination_schema(self):
response = requests.get(
f'{API_URL}/v1/prices/past_year',
params={'commodity': 'WTI_USD', 'page': 1, 'per_page': 10}
)
data = response.json()
# Validate pagination metadata
assert 'meta' in data
assert 'page' in data['meta']
assert 'per_page' in data['meta']
assert 'total' in data['meta']
assert 'has_next' in data['meta']Run on Backend Deploys
# In oilpriceapi-api repo: .github/workflows/deploy.yml
jobs:
deploy:
steps:
- name: Deploy to production
run: ...
- name: Run SDK contract tests
run: |
# Clone SDK repo
git clone https://github.com/OilpriceAPI/python-sdk.git
cd python-sdk
# Run contract tests against deployed API
pytest tests/contract/ --api-url=https://api.oilpriceapi.com
- name: Create issue if contract broken
if: failure()
run: |
gh issue create \
--title "SDK Contract Broken by Backend Deploy" \
--label "bug,priority: critical"Acceptance Criteria
- Contract test suite created
- Tests validate all SDK assumptions
- Tests run on backend deploys
- Failures create GitHub issues automatically
- Documentation for maintaining contracts
Estimated Effort
Time: 4 hours