## 2. API Design

### 2.1 Key Domain Objects

```json

{

"ParkingLot": {

"lotId": "string",

"name": "string",

"address": "string",

"timezone": "string"

},

"Floor": {

"floorId": "string",

"lotId": "string",

"level": "integer"

},

"Spot": {

"spotId": "string",

"floorId": "string",

"type": "COMPACT | LARGE | MOTORBIKE | EV_CHARGING | DISABLED",

"status": "AVAILABLE | OCCUPIED | OUT_OF_SERVICE | RESERVED",

"zone": "string"

},

"Ticket": {

"ticketId": "string",

"lotId": "string",

"vehicle": { "plate": "string?", "type": "string" },

"entryGateId": "string",

"entryAt": "ISO8601",

"assignedSpotId": "string",

"status": "ACTIVE | CLOSED | LOST"

},

"Payment": {

"paymentId": "string",

"ticketId": "string",

"amount": "decimal",

"currency": "string",

"method": "CARD | CASH | WALLET",

"status": "string",

"providerRef": "string"

}

}

```

### 2.2 Public-facing APIs

#### Entry Flow

`POST /v1/tickets/entry`

```json

// Request

{

"lotId": "L1",

"gateId": "GATE_E_01",

"vehicle": { "type": "CAR", "plate": "SGP1234A" },

"preferences": { "needEvCharging": false, "needDisabled": false }

}

// Response

{

"ticketId": "T_9f...",

"issuedAt": "2026-02-24T10:01:22+08:00",

"spot": { "spotId": "S_2_041", "floorId": "F2", "zone": "B" },

"barcode": "....",

"status": "ACTIVE"

}

```

#### Exit Quote

`GET /v1/tickets/{ticketId}/quote`

```json

{

"ticketId": "T_9f...",

"entryAt": "...",

"exitAt": "...",

"amount": 6.50,

"currency": "SGD",

"breakdown": [{"rule": "weekday_hourly", "amount": 6.50}]

}

```

#### Payment

`POST /v1/payments`

```json

{

"ticketId": "T_9f...",

"method": "CARD",

"paymentToken": "tok_xxx",

"idempotencyKey": "uuid-unique"

}

```

#### Exit Confirmation

`POST /v1/tickets/{ticketId}/exit`

```json

{

"gateId": "GATE_X_02",

"paidPaymentId": "P_12...",

"vehiclePlate": "SGP1234A"

}

```

#### Availability

`GET /v1/lots/{lotId}/availability?spotType=COMPACT`

```json

{ "lotId": "L1", "counts": { "COMPACT": 120, "EV_CHARGING": 8 } }

```

### 2.3 Admin APIs

* `PUT /v1/spots/{spotId}`: Update status or type.

* `POST /v1/pricingRules/publish`: Publish a new rule version.

* `GET /v1/reports/occupancy?from=...&to=...`: Generate occupancy reports.

### 2.4 API Correctness Rules

1. **Idempotency**: All state-changing endpoints must support `Idempotency-Key` to safely handle retries.

2. **Concurrency**: Gate endpoints must tolerate retries without double-allocating spots.

3. **Clock Source**: Use server time (anchored to the lot's timezone) for all billing calculations.

Submissions

Displaying Solutions with Scores Ranging from 1 to 10