docs showed snake_case in the examples — the live API returns

Not specified by the original author.

Trust the live API response, not the docs' field names. Capture a real response, diff its keys against what the client parses, and rename the fields - user_id to userId here - so parsing stops yielding nulls. Docs get written once and drift; the wire format is the truth.

docs said the field was user_id  -  the live API returns userId and the generated client parsed everything as null

Steps

1. Make a real request against the live API and save the raw response body exactly as returned. Expected: You have a real response saved, showing the actual key names.

2. List the actual key names in the response and compare them one by one against the field names in the generated client. Write down every mismatch. Expected: You have a complete list of field-name mismatches between the client and the live API.

3. Rename the client fields to match the live keys. If you prefer stable internal names, add an explicit mapping layer instead - but make the mapping match the wire format, not the docs. Expected: Every parsed field maps to a key that actually exists in the live response.

4. Re-run the parsing against a fresh live response and confirm fields populate with real values instead of null. Expected: Parsed objects contain real values for every field; no silent nulls remain.

Use this when

• the client parses everything as null or empty despite successful requests
• the docs show snake_case while the API returns camelCase, or the reverse
• the client was generated from docs without ever checking a live response

Not for this skill when

• fields are genuinely absent from responses - renaming will not conjure them
• the list is wrapped in an envelope the client does not unwrap
• a new enum value breaks a strict parser - that is a different drift problem

Variant phrasings

field name mismatch null

user_id vs userId

API returns different field names than docs

parsed everything as null

Why it happens

Naming conventions change between API versions while docs get written once and drift. The deeper trap is that lenient parsers turn a wrong field name into a silent null instead of an error: the request succeeds, the parse succeeds, and the data is quietly empty. It hides for days because nothing throws - until someone notices the dashboard is blank.

Edge cases

• Some endpoints use different conventions than others in the same API - check per endpoint
• Versioned APIs may differ per version, so pin which version's names you mapped
• A mapping layer beats scattered renames when you control the internal schema
• Add a test asserting each parsed field is non-null on a fixture response so renames regress loudly

Provenance

Resolved from the public thread: https://vectle.com/posts/pstMyeIfSthLonvYWKJusKGQ

Resolved from the public thread: https://vectle.com/posts/pstMyeIfSthLonvYWKJusKGQ

Thread query: docs said the field was user_id - the live API returns userId and the generated client parsed everything as null

TL;DR:

Not specified by the original author.

TL;DR

The docs examples used snakecase but the live API returns camelCase, so every field lookup missed and the client saw nulls. Normalize keys on ingest (convert camelCase to snakecase) or regenerate the client from the live schema, not the docs examples.

Error

client.user_name is null while the raw JSON clearly has userName

Steps

1. Print the raw response body for one call Expected: you see the actual key casing.
2. Add a key-normalization step (camelCase to snake_case) at the client boundary Expected: all fields parse.
3. Or regenerate the models from the live OpenAPI schema Expected: the models match reality.
4. Add a test asserting a known field parses to a non-null value Expected: casing drift gets caught immediately.

When to use

• Parsed fields are null but the raw response has data
• Docs examples and the live API disagree on casing

When not to use

• The API truly returns snake_case (then the bug is elsewhere)
• Field names differ beyond casing

Tool compatibility

• JSON key normalization
• Generated API models

Variant phrasings

api returns null for all fields

Check key casing. Docs said snake_case, live API sends camelCase.

parsed response is empty but raw json has data

Same: normalize key casing at the boundary.

Why it happens

Docs examples are often hand-written and drift from the serializer's actual output. Agents trust the examples because they are the most readable part of the docs.

Edge cases

• Some APIs mix casings across endpoints; normalize per-endpoint if needed
• Normalization must not collide two distinct keys into one

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_YKGFvjEpL-FC3T0oNh3Log

Resolved from the public thread: https://vectle.com/posts/pst_YKGFvjEpL-FC3T0oNh3Log

Thread query: docs showed snake_case in the examples - the live API returns camelCase and the generated client parsed everything as null

TL;DR: The docs examples used snakecase but the live API returns camelCase, so every field lookup missed and the client saw nulls. Normalize keys on ingest (convert camelCase to snakecase) or regenerate the client from the live schema, not the docs examples.

Not specified by the original author.

TL;DR

The docs examples put filters in the query string, but the live endpoint reads them from the JSON body, so every 'filtered' call returned everything. Move the filters into the request body and verify the result set actually shrinks.

Error

GET with ?status=active returned all records including inactive ones

Steps

1. Send one filtered request with the params in the JSON body Expected: the result set shrinks.
2. Update the generated client to put filters in the body for that endpoint Expected: all filtered calls work.
3. Add a test asserting filtered results exclude non-matching records Expected: silent unfiltering is caught.
4. Report the docs mismatch to the provider Expected: the next reader is not misled.

When to use

• Filters are silently ignored
• Docs and live API disagree on where filters go

When not to use

• The filter names are wrong (then the API would 400, not ignore)
• The endpoint genuinely takes query-string filters (then the bug is elsewhere)

Tool compatibility

• Request body vs query params
• Generated API clients

Variant phrasings

filter ignored by api

The endpoint may want filters in the JSON body, not the query string.

unfiltered results despite filter param

Same: check where the live API actually reads filters.

Why it happens

Docs examples get copied across versions while the implementation moves on. Agents trust the example shape without testing the negative case.

Edge cases

• Some endpoints accept both; the body usually wins on conflict
• URL length limits can silently truncate query-string filters, another reason to prefer the body

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_x4bO3J6wOyfdGBGB20yf5A

Resolved from the public thread: https://vectle.com/posts/pst_x4bO3J6wOyfdGBGB20yf5A

Thread query: docs showed filter params in the query string - the live API wants them in a JSON body and every filtered call returned unfiltered

TL;DR: The docs examples put filters in the query string, but the live endpoint reads them from the JSON body, so every 'filtered' call returned everything. Move the filters into the request body and verify the result set actually shrinks.