7 Blind Spots an API Review Catches

The API Mismatches You Only Notice After Implementation

Treat an API design review as just "checking endpoints and parameters," and bugs slip through. Details like nullability or error formats are exactly the kind of thing reviewers skip past, assuming "it'll get decided during implementation." Then the frontend and backend connect, everyone hits an unexpected value or error shape, and the work has to be redone — a bug a design-phase review could have caught.

This article breaks the mismatches that typically surface after implementation into seven review items, each with the kind of bug it tends to produce.

7 Things to Check in a Review

1. Nullable vs. Optional

For every field, be explicit about whether it's "always present but can be null" or "may be absent entirely."
Typical bug: The frontend dereferences response.user.name unconditionally, then crashes the moment a deactivated user returns user: null.

2. A Single Error Shape

If every endpoint returns errors differently, the frontend ends up handling each one as a special case. Check whether { error: string } and { errors: [{ field, message }] } coexist.
Typical bug: One endpoint returns an array only on validation errors; the frontend's shared error component assumes a string and renders [object Object] on screen.

3. Offset vs. Cursor Pagination

Decide up front. For large lists or frequently-written data, offset pagination causes duplicates or gaps.
Typical bug: A new row gets inserted while a user pages through a list; offsets shift and the same row appears twice, or one gets skipped entirely.

4. Naming Consistency

Pin down snake_case vs. camelCase, and whether created_at or createdAt is canonical — and whether conversion happens in the serializer or the frontend.
Typical bug: A new endpoint alone returns camelCase; the frontend reuses existing type definitions and the field comes back undefined.

5. Idempotency

Will a duplicate POST create a duplicate record? This matters most for payment and signup endpoints.
Typical bug: A user double-clicks during a slow request and ends up with two identical orders.

6. Versioning and Backward Compatibility

Can fields be added, removed, or retyped without breaking existing clients? Decide the migration path for breaking changes too.
Typical bug: A field's type changes from string to number; an older mobile app version fails to parse the response and crashes.

7. Where Authorization Is Checked

Verify not just "who can call this" but "whose data this may return." List endpoints are especially prone to leaking other users' data.
Typical bug: A project list endpoint filters only by project_id and forgets an ownership check — rewrite the URL and you can see someone else's project.

Running the Review

Debating all seven every time is heavy. Turn them into a checklist attached to the PR or design doc before implementation starts, and the review moves faster.

• Is nullable/optional documented for every field?
• Does the error response shape match existing endpoints?
• Has a pagination strategy been chosen for list endpoints?
• Does naming match existing type definitions?
• Has idempotency been considered for write endpoints?
• Does the change avoid breaking existing clients?
• Does the authorization check go as far as "this user's data only"?

How Bugoon Fits In

If these seven points only get settled in a review meeting, mismatches discovered after implementation tend to circulate in chat and never get recorded. Bugoon lets anyone report an issue directly from the screen via the embedded widget, so when a review gap surfaces after implementation, it can be filed straight into a GitHub Issue with a screenshot and the steps taken. Whoever picks it up — frontend or backend — can see exactly which endpoint and which response shape caused it, reproducible from the report itself.