API Log Design

Date: 2026-04-04 Scope: Outbound HTTP request logging only. Inbound request logging is out of scope (separate table request_logs when needed).

Purpose

Log every outbound HTTP request made by this application to external APIs. Provides an audit trail for debugging failed polls, tracking latency, and monitoring API health over time.

Table: `api_logs`

Column	Type	Nullable	Notes
`id`	BIGINT UNSIGNED	no	Auto-increment PK
`service`	VARCHAR(32)	no	Identifies the external service: `fuel_finder`, `fred`, `postcodes_io`, `vonage`, `onesignal`
`method`	VARCHAR(8)	no	HTTP method: `GET`, `POST`
`url`	VARCHAR(512)	no	Full URL including query string
`status_code`	SMALLINT UNSIGNED	yes	HTTP response status code; null if request threw an exception
`duration_ms`	SMALLINT UNSIGNED	no	Round-trip response time in milliseconds
`error`	TEXT	yes	Exception message if the request failed; null on success
`created_at`	DATETIME	no	When the request was made

No updated_at — rows are write-once.

ApiLogger Service

A thin ApiLogger service wraps Laravel's Http:: facade. It:

Records start time
Makes the HTTP request inside a try/catch
Writes an api_logs row with URL, status, duration, and error (if any) — always, via try/finally
Re-throws any exception so the calling service retains full control over error handling

FuelPriceService (and future services hitting external APIs) inject ApiLogger and use it instead of calling Http:: directly.

What Gets Logged

Every outbound GET and POST — including:

Fuel Finder OAuth token requests (POST /oauth/generate_access_token)
Fuel Finder price batch fetches (GET /pfs/fuel-prices?batch-number=N)
Fuel Finder station metadata fetches (GET /pfs?batch-number=N)
Future: FRED Brent crude fetch, Postcodes.io lookups, Vonage, OneSignal

Out of Scope

Response body storage (not logged — too large, not needed)
Request headers or credentials (never logged)
Inbound request logging (request_logs — separate feature)
Relation between api_logs and station_prices rows

Pruning

Old rows can be pruned on a schedule (e.g. keep 30 days). Not in scope for this implementation but the table should support it via created_at index.

2.3 KiB Raw Blame History