API Versioning

Housr maintains two API versions. API v2 is the standard for all new work. API v1 is legacy and being phased out over time.

When to Use Which

Scenario	Use
Building a new endpoint	API v2 (always)
New feature in the App	API v2
New feature in the Webapp	API v2
Endpoint only exists in v1	Use v1, plan migration to v2
Modifying an existing v1 endpoint	Migrate it to v2 instead

Rule of thumb: Never add new functionality to API v1. If you need to change a v1 endpoint, build the replacement in v2 and update the consumers.

API v1 (Housr-API)

Monolithic Laravel application
Endpoints under a single route file
JWT auth via plain Authorization header or jwt form field
$USA global flag for regional logic
Still used by the App for many endpoints that haven’t been migrated

API v2 (Housr-API2)

Laravel Modules architecture — each domain is a separate module
RESTful conventions
Bearer JWT authentication
LegacyJwtGuard for backwards compatibility with v1 tokens
Firebase JWT support
Module-specific migrations, models, controllers, and tests
All new features go here

How Consumers Use Both APIs

Housr-App

The App has two axios instances defined in src/lib/axios.ts:

apiV1: Points to the v1 API URL. Sends JWT as a form field and plain Authorization header.
apiV2: Points to the v2 API URL. Sends JWT as Bearer token. Uses application/json for PATCH requests.

Feature hooks call the appropriate instance based on which API has the endpoint.

Housr-Webapp

The Webapp’s src/helpers/api.ts provides get(), post(), and related helpers. These default to API v2. The post() and postFormData() helpers accept a useLegacyApi flag to switch to v1 when needed.


API_URL         → API v2 (default)
LEGACY_API_URL  → API v1 (when useLegacyApi: true)

Housr Portal

Portal does not call either API. It accesses the shared database directly via Eloquent.

Migration Strategy

The long-term plan is to eliminate API v1 entirely. Migration happens incrementally:

Identify a v1 endpoint that needs changes or is heavily used
Build the equivalent in API v2 as a module endpoint
Update the App and/or Webapp to use the new v2 endpoint
Once no consumers use the v1 endpoint, mark it as deprecated
Eventually remove the v1 endpoint

There is no hard timeline — migration happens opportunistically as features are built or modified.