API Setup

API Setup

Everything you need to configure, test, and integrate with the Bill Organizer API.

---

Environment Configuration

Add the following to your .env file:

# Sanctum — token-based API authentication
SANCTUM_STATEFUL_DOMAINS=localhost,localhost:3000,127.0.0.1,127.0.0.1:8000,::1
SANCTUM_TOKEN_PREFIX=

# CORS — allowed origins for cross-origin requests
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8000

# Rate limiting (requests per minute per user)
API_RATE_LIMIT=60

For production, replace the CORS origins with your actual frontend domains:

CORS_ALLOWED_ORIGINS=https://yourdomain.com,https://app.yourdomain.com

---

Quick Start

1. Start the server

php artisan serve
# Available at http://localhost:8000

2. Register and obtain a token

curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Your Name",
    "email": "you@example.com",
    "password": "password123",
    "password_confirmation": "password123"
  }'

Save the token from the response.

3. Make authenticated requests

curl http://localhost:8000/api/v1/bills \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Accept: application/json"

---

Postman Collection

A complete Postman collection is available at docs/postman-collection.json.

How to Import

1. Open Postman
2. Click Import
3. Select docs/postman-collection.json
4. Set the collection variable base_url to http://localhost:8000/api/v1
5. Run the Login or Register request — the collection automatically saves the token to api_token
6. All other requests will use the saved token

Collection Variables

Variable	Description	Default
base_url	API base URL	http://localhost/api/v1
api_token	Bearer token (auto-set after login)	(empty)

---

Common Use Cases

Create a Category, Then a Bill

# 1. Create a category
curl -X POST http://localhost:8000/api/v1/categories \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Entertainment","icon":"🎬","color":"#FF5733"}'

# 2. Create a bill using the category ID returned above
curl -X POST http://localhost:8000/api/v1/bills \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Netflix Subscription",
    "amount": 15.99,
    "due_date": "2026-05-01",
    "category_id": 1,
    "is_recurring": true,
    "recurrence_period": "monthly",
    "tags": ["entertainment", "subscription"]
  }'

Record a Payment

curl -X POST http://localhost:8000/api/v1/transactions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bill_id": 1,
    "amount": 15.99,
    "payment_date": "2026-04-23",
    "payment_method": "credit_card",
    "notes": "Monthly payment"
  }'

Get Upcoming Bills

# Bills due in the next 14 days
curl "http://localhost:8000/api/v1/bills/upcoming?days=14" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Advanced Search and Filter

# Unpaid bills in category 1, sorted by due date
curl "http://localhost:8000/api/v1/bills?status=unpaid&category_id=1&sort_by=due_date" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Column-specific search
curl "http://localhost:8000/api/v1/bills?search=title:Netflix" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Transactions in a date range
curl "http://localhost:8000/api/v1/transactions?date_from=2026-01-01&date_to=2026-03-31" \
  -H "Authorization: Bearer YOUR_TOKEN"

---

Running API Tests

# Run all API tests
php artisan test tests/Feature/Api

# Run a specific test file
php artisan test tests/Feature/Api/V1/AuthControllerTest.php

# Run with code coverage
php artisan test --coverage

Test files included:

File	Coverage
AuthControllerTest.php	Login, register, logout, profile (10 tests)
BillControllerTest.php	Full CRUD + mark as paid
CategoryControllerTest.php	Full CRUD
TransactionControllerTest.php	Full CRUD + file upload
TeamControllerTest.php	Team management

---

Security Best Practices

Token Management

• Never expose tokens in client-side code or version control
• Use different tokens per device or integration
• Revoke tokens immediately if compromised
• Set token expiration in config/sanctum.php:

'expiration' => 60 * 24 * 7, // 7 days in minutes

HTTPS Only

FORCE_HTTPS=true
SESSION_SECURE_COOKIE=true

Rate Limiting

Adjust per your traffic needs:

API_RATE_LIMIT=100

Implement exponential backoff when you receive a 429 Too Many Requests response and check the X-RateLimit-Reset header for when the limit resets.

---

Troubleshooting

401 Unauthorized

• Verify the token is in the Authorization: Bearer {token} header
• Check the token has not been revoked (re-login to get a new one)

403 Forbidden — Team Required

• The user must belong to at least one team
• Switch to an active team: POST /api/v1/teams/{team}/switch

422 Validation Error

• Check your request payload against the API documentation
• Response body includes field-level error messages

429 Too Many Requests

• You have hit the rate limit
• Wait for the reset time shown in X-RateLimit-Reset
• Add exponential backoff to your client

CORS Errors (browser clients)

• Add your frontend origin to CORS_ALLOWED_ORIGINS in .env
• Include Accept: application/json in every request
• Check browser DevTools console for specific CORS details

---

Production Deployment Checklist

• APP_ENV=production and APP_DEBUG=false
• Specific CORS_ALLOWED_ORIGINS (no wildcards)
• HTTPS enabled with SESSION_SECURE_COOKIE=true
• Database configured and migrated
• Rate limiting tuned to expected traffic
• Monitoring and error tracking set up
• Queue workers running (for webhook delivery)
• Cron scheduler configured

Optimization Commands

php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan migrate --force
php artisan queue:restart

---

API Versioning Strategy

The current API is v1. To introduce breaking changes without disrupting existing clients:

1. Create routes/api/v2.php
2. Create controllers under app/Http/Controllers/Api/V2/
3. Register v2 routes in routes/api.php
4. Document changes separately
5. Maintain v1 for backward compatibility during a deprecation period

---

Support

• Documentation: API Overview
• GitHub Issues: github.com/4msar/bill-organizer/issues
• Email: support@bills.msar.me