Overview
The Parking API provides functions to fetch parking spot status, create/update/delete spots (admin only), and manage reservations. It includes intelligent caching to reduce API calls and localStorage fallback for offline support.
Import
import {
fetchParkingStatus,
reserveSpot,
releaseSpot,
createSpot,
updateSpot,
deleteSpot,
invalidateParkingCache,
bulkAssignSpots,
bulkDeleteSpots
} from './js/api/parking.js';
Caching Behavior
The Parking API implements a two-layer caching strategy:
- Memory Cache: Stores parking status in memory with configurable TTL (default 15 seconds)
- localStorage Cache: Persistent fallback storage when API is unavailable
Cache Keys
STORAGE_KEY_SPOTS
string
default:"'sparking_spots_local'"
localStorage key for cached parking spots data
STORAGE_KEY_SPOTS_SYNC
string
default:"'sparking_spots_synced_at'"
localStorage key for last sync timestamp (ISO 8601 format)
Cache Duration
The cache TTL is configurable via CONFIG.PERFORMANCE.CACHE_PARKING_STATUS (default: 15000ms).
fetchParkingStatus
Retrieves the current status of all parking spots with intelligent caching.
Function Signature
async function fetchParkingStatus(): Promise<Array<Spot>>
Returns
Array of parking spot objectsUnique spot identifier (e.g., “A1”, “B2”)
Spot status: 1 = available, 2 = occupied, 3 = reserved
Associated zone ID (empty string if unassigned)
Vehicle license plate if spot is occupied/reserved
Creation timestamp (ISO 8601)
Last update timestamp (ISO 8601)
Cache Behavior
- Memory cache hit: Returns cached data if less than 15 seconds old
- API call: Fetches from
CONFIG.GET_STATUS_API_URL and updates both memory and localStorage
- Fallback: Returns localStorage data if API fails
- Throws: Error if both API and localStorage are unavailable
Usage Example
import { fetchParkingStatus } from './js/api/parking.js';
try {
const spots = await fetchParkingStatus();
console.log(`Loaded ${spots.length} parking spots`);
const availableSpots = spots.filter(s => s.status === 1);
console.log(`${availableSpots.length} spots available`);
} catch (error) {
console.error('Failed to load parking status:', error);
}
reserveSpot
Creates a reservation for a specific parking spot.
Function Signature
async function reserveSpot(
spotId: string,
licensePlate: string,
durationMinutes: number
): Promise<ReservationResponse>
Parameters
ID of the parking spot to reserve (e.g., “A1”)
Vehicle license plate number
Reservation duration in minutes
Returns
Reservation confirmation object (structure depends on backend API)
Behavior
- Invalidates parking cache immediately to force refresh
- Sends POST request to
CONFIG.RESERVATION_API_URL
- Throws error if reservation fails (display to user)
Usage Example
import { reserveSpot } from './js/api/parking.js';
try {
const result = await reserveSpot('A1', 'ABC-123', 60);
console.log('Reservation successful:', result);
} catch (error) {
alert(`Reservation failed: ${error.message}`);
}
releaseSpot
Cancels a reservation and releases the parking spot.
Function Signature
async function releaseSpot(spotId: string): Promise<boolean>
Parameters
ID of the parking spot to release
Returns
true if release succeeded, false if it failed
Behavior
- Invalidates parking cache immediately
- Sends POST request to
CONFIG.RELEASE_API_URL
- Returns
false instead of throwing on error
Usage Example
import { releaseSpot } from './js/api/parking.js';
const success = await releaseSpot('A1');
if (success) {
console.log('Spot released successfully');
} else {
console.error('Failed to release spot');
}
Admin Functions
createSpot
Creates a new parking spot (admin only).
async function createSpot(data: SpotData): Promise<CreateResponse>
Unique spot ID (will be converted to uppercase)
Zone assignment (optional)
Initial status (default: 1 = available)
import { createSpot } from './js/api/parking.js';
const result = await createSpot({
id: 'C5',
lat: -33.4372,
lng: -70.6506,
desc: 'Section C - Row 5',
zone_id: 'zone_vip',
status: 1
});
updateSpot
Updates an existing parking spot (admin only).
async function updateSpot(spotId: string, data: Partial<SpotData>): Promise<UpdateResponse>
Partial object with fields to update (desc, zone_id, lat, lng, status, etc.)
import { updateSpot } from './js/api/parking.js';
// Update zone assignment
await updateSpot('A1', { zone_id: 'zone_premium' });
// Update description
await updateSpot('B2', { desc: 'Handicap Accessible' });
deleteSpot
Deletes a parking spot (admin only).
async function deleteSpot(id: string): Promise<boolean>
import { deleteSpot } from './js/api/parking.js';
const success = await deleteSpot('C5');
if (success) {
console.log('Spot deleted');
}
Utility Functions
invalidateParkingCache
Manually invalidates the memory cache to force a fresh API call.
function invalidateParkingCache(): void
import { invalidateParkingCache, fetchParkingStatus } from './js/api/parking.js';
// Force refresh after external update
invalidateParkingCache();
const freshData = await fetchParkingStatus();
bulkAssignSpots
Assigns multiple spots to a zone in series.
async function bulkAssignSpots(
zoneId: string,
spotIds: Array<string>
): Promise<Array<BulkResult>>
Target zone ID (empty string to unassign)
Array of spot IDs to assign
{ id: string, success: boolean, res?: any, error?: any }
Example:
import { bulkAssignSpots } from './js/api/parking.js';
const results = await bulkAssignSpots('zone_vip', ['A1', 'A2', 'A3']);
const successCount = results.filter(r => r.success).length;
console.log(`${successCount}/${results.length} spots assigned`);
bulkDeleteSpots
Deletes multiple spots in series.
async function bulkDeleteSpots(spotIds: Array<string>): Promise<Array<BulkResult>>
import { bulkDeleteSpots } from './js/api/parking.js';
const results = await bulkDeleteSpots(['C1', 'C2', 'C3']);
const deletedCount = results.filter(r => r.success).length;
console.log(`${deletedCount} spots deleted`);
Error Handling
All async functions can throw errors. Best practices:
import { fetchParkingStatus, reserveSpot } from './js/api/parking.js';
// Wrap in try-catch
try {
const spots = await fetchParkingStatus();
await reserveSpot('A1', 'XYZ-789', 120);
} catch (error) {
console.error('Operation failed:', error.message);
// Handle error (show toast, modal, etc.)
}
// Or use .catch()
fetchParkingStatus()
.then(spots => {
console.log('Loaded spots:', spots.length);
})
.catch(error => {
console.error('Failed to load spots:', error);
});
Offline Support
All functions include localStorage fallback:
- Reads: Fall back to cached data if API is unavailable
- Writes: Save changes locally with
_local: true flag to sync later
Local-only changes are marked with _local: true in the response object.