Legacy → Standardized Migration

The Defentry API serves two response formats from the same endpoints. You choose per request with the X-API-Version header — the paths, methods, and request bodies are identical, so migrating is purely about how you read responses.

View	How you select it	Envelope
Legacy (default)	Omit X-API-Version	Original formatting and varied error shapes
Standardized	Send X-API-Version: 2026-06-12	ISO-8601 datetimes, real JSON booleans, one canonical error envelope

Preview both in the Explorer

The API Explorer renders both views with the version selector at the top — the same operation, side by side. (Server-wide, an operator can set API_NORMALIZE_ALL=true to force standardized for every request.)

What changes when you switch

1. Datetimes

- "created_at": "2026-06-16 21:02:05"
+ "created_at": "2026-06-16T21:02:05Z"

Legacy datetimes are space-separated and timezone-less. Standardized datetimes are ISO-8601 / RFC 3339 UTC with a Z suffix. Update your parsers to read the Z form. Pure date fields (e.g. activation_date) stay date-only in both.

2. Booleans

- "is_active": 1
+ "is_active": true

Legacy returns flags as raw 1/0. Standardized returns real JSON booleans. Stop coercing integers — treat is_*, has_*, can_*, show_*, enable_*, and skip_* fields as booleans.

3. Error envelope

Legacy errors arrive in several shapes depending on the endpoint and failure type. Standardized collapses them all into one envelope:

- { "errors": [ { "status": "422", "title": "...", "detail": "..." } ] }
- { "errors": { "email": ["The email field is required."] } }
- { "error": "Not found" }
- { "message": "Unauthenticated." }
+ {
+   "error": {
+     "code": "VALIDATION_ERROR",
+     "message": "The given data was invalid.",
+     "details": [ { "field": "email", "issue": "The email field is required." } ]
+   }
+ }

Branch on error.code (and the HTTP status), never on message text or the old envelope shape. See Response & Error Conventions for the full code table.

Migration checklist

• [ ] Send X-API-Version: 2026-06-12 on every request once you are ready.
• [ ] Parse all timestamps as ISO-8601 / RFC 3339, handling the Z suffix.
• [ ] Treat boolean-named fields as JSON booleans, not 1/0.
• [ ] Read errors from error.code / error.message / error.details.
• [ ] Stop depending on any legacy top-level error keys.
• [ ] Re-test against the API Explorer standardized examples.

Rollout strategy

Because the format is request-driven, you can migrate without a flag day:

1. Keep production on legacy (omit the header).
2. In a staging or canary path, send X-API-Version: 2026-06-12 and verify your datetime, boolean, and error handling against real responses.
3. Flip traffic to send the header once parsing is confirmed. Roll back instantly by dropping the header if anything regresses.

Source of truth

The two behaviors are defined in the gateway's config/api.php and app/Support/ResponseStandard.php; this page mirrors what the integration spec's X-API-Version parameter documents for each view.