API Reference

Complete Harbor Parking REST API documentation with interactive examples

Welcome to Harbor Parking API

Our REST API enables developers to integrate parking spot sharing functionality into any application. Built with modern standards and developer experience in mind.

Base URL

All API requests should be made to:

https://harbor-parking.vercel.app/api

For local development:

http://localhost:3000/api

Authentication

All endpoints require JWT authentication except where noted. Include your token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Get Started with Authentication

Learn how to obtain and use JWT tokens for API access

Request/Response Format

Content Type

All requests and responses use JSON:

Content-Type: application/json

Request Format

curl -X POST "https://harbor-parking.vercel.app/api/parking-spots" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "spot_number": "A-15",
    "location": "Level 2 Parking Garage"
  }'

Response Format

{
  "spot": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "spot_number": "A-15",
    "owner_id": "456e7890-e89b-12d3-a456-426614174001",
    "building_section": "Level 2 Parking Garage",
    "is_verified": false,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

HTTP Status Codes

The API uses standard HTTP status codes:

2xx Success

• 200 OK - Request successful
• 201 Created - Resource created successfully

4xx Client Errors

• 400 Bad Request - Invalid request data or validation errors
• 401 Unauthorized - Missing or invalid authentication token
• 403 Forbidden - Insufficient permissions or account not approved
• 404 Not Found - Resource not found
• 409 Conflict - Resource already exists or conflicts with existing data

5xx Server Errors

• 500 Internal Server Error - Unexpected server error

Error Response Format

All errors follow a consistent format:

{
  "error": "Validation failed",
  "details": {
    "spot_number": {
      "_errors": ["Spot number is required"]
    }
  }
}

The API uses standard HTTP status codes to indicate the success or failure of requests. See the error examples in each endpoint documentation for details.

Rate Limiting

API requests are rate limited to ensure fair usage:

• 100 requests per minute per authenticated user
• 1000 requests per hour per authenticated user
• Rate limit headers included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

API Endpoints Overview

Profile & Authentication

Manage user profiles and authentication

Get Profile

Retrieve authenticated user’s profile

Update Profile

Update user profile information

Dashboard

Get comprehensive dashboard data

Get Dashboard

Retrieve user dashboard with stats, spots, and claims

Parking Spots

Manage parking spot registration and ownership

List Spots

Get parking spots with filtering

Create Spot

Register a new parking spot

Update Spot

Update parking spot details

Delete Spot

Remove a parking spot

Availabilities

Manage parking spot availability windows

List Availabilities

Get availability windows with filtering

Create Availability

Set spot availability window

Update Availability

Modify availability details

Delete Availability

Remove availability window

Claims

Manage parking spot reservations

List Claims

Get claims with filtering options

Create Claim

Claim an available parking spot

Update Claim

Update claim status or details

Delete Claim

Cancel a parking spot claim

OpenAPI Specification

OpenAPI Specification

Complete machine-readable API specification in OpenAPI 3.0 format

Interactive Playground

Try API endpoints directly in your browser with live data:

The interactive playground requires a valid JWT token. Obtain one by logging into the Harbor Parking web application.

Webhooks (Coming Soon)

Real-time notifications for parking events:

• New spot registrations
• Availability changes
• Claim submissions and updates
• Admin approvals

Need Help?

Quickstart Guide

Get up and running in 5 minutes

Community Support

Connect with other developers

Report Issues

Bug reports and feature requests