7. Chapter review

The access/normalization layer should handle this structural variation. This layer sits between the raw API response and your application logic, transforming different response shapes into a consistent interface.

Expose a single next_token field that holds either a cursor or next-URL. This unified field lets pagination code work the same way regardless of which endpoint format you're using. The normalizer extracts the pagination token from wherever it appears in the response and places it in this standardised field.

Perform type coercion in the normalizer function, as early as possible in your data pipeline. This is where you transform varying input formats into your application's standard representation.

The canonical representation should be a numeric float (129.5). Use float() conversion with appropriate error handling. Numeric representation makes calculations straightforward and prevents string-comparison issues. Format the number as a string with proper decimal places only when displaying to users.

Enum drift occurs when the same logical value appears in different formats across endpoints. Common examples:

• "Shipped" vs "shipped" (capitalisation differences)
• "Cancelled" vs "canceled" (spelling variations)

Harmonize by normalising to lowercase in your canonical model: status.lower(). Then validate against an allowed set like {"shipped", "pending", "cancelled"} to catch unexpected variations. Store the canonical lowercase version internally; only apply proper capitalisation when displaying to users.

Use the extended safe_get() -- the navigation-page version that understands [N] path segments:

time = safe_get(place, "opening_hours.periods[0].open.time", "Closed")

One call covers every failure mode. If opening_hours is missing or null, if periods is an empty list, if open is missing, or if time itself is absent, the helper short-circuits at the failing step and returns "Closed". The dict-only version from flexible-access would force you to fetch the array, guard it, index into it, then fetch the nested field -- four lines where one path string now does the work.

• id: required field. Fail fast with a clear error. Without an ID, you can't process this record meaningfully. Use require(obj, "id"), which raises immediately if missing.
• customer.email: recommended field. Provide a sensible default like "Unknown" or "No email provided". The record can still be processed; log a warning since the field is typically expected.
• discount.value when promo exists: conditionally required field. If a promo object is present, discount.value becomes required for that record. Either validate this rule and fail with a clear error, or drop the entire discount structure if the value is missing. Don't silently continue with partial discount data.

Fail fast: raise an exception immediately when data is missing or invalid. This stops processing and forces the issue to be addressed. Use this for truly required data without which the record is meaningless.

Example: a missing id field on an order. Without an ID you can't track, update, or reference this order, so processing it would corrupt your system.

Fail soft: provide a default value and continue processing. This keeps the application functional when optional data is missing.

Example: a missing profile_image_url for a user. You can default to a generic avatar and the rest of the user functionality works fine. The missing image doesn't prevent authentication, authorisation, or other core features.

Step 1: exploration. Use diagnostic tools to understand each variant's structure. Pretty-print responses, identify signature fields, document nesting patterns, note optional sections.

Step 2: design the canonical shape. Choose field names, decide on types (string vs number, ISO timestamps, enum values), define required vs optional fields, establish the internal structure.

Step 3: detection logic. Write code to identify which variant you're processing, usually by checking for signature fields unique to each format.

Step 4: field mappers. Extract data from each variant's specific location and apply type coercion, timestamp normalisation, and enum harmonisation.

Step 5: defensive patterns. Add safe accessors for nested data, provide defaults for optional fields, use explicit error policies for required fields.

Step 6: test with all variants. Verify the normalizer produces identical canonical output for every variant. Test edge cases: missing optionals, malformed data.

Step 7: document and maintain. Comment the detection logic, note which fields are required, document default behaviours so future maintainers understand your decisions.

The eight patterns:

1. Field mapping (renaming fields)
2. Type coercion (string to number conversion)
3. Time unification (timestamp format normalisation)
4. Enum harmonization (status value standardisation)
5. Join strategy (embedding related data)
6. Pagination adapter (token extraction)
7. Optional field handling (defaults and nulls)
8. Array processing (nested object extraction)

Real APIs rarely fit neat categories. You might meet an API that needs only field mapping and type coercion; another might require six of the eight. Knowing the complete toolkit lets you recognise which patterns apply to a specific integration quickly. You're not memorising solutions -- you're building pattern recognition that helps you assess new APIs faster and implement normalizers with confidence.