Known Inconsistencies and Gotchas

Use this guide to prevent integration bugs caused by differences between expected and actual API behavior.

Why This Document Exists

• Inconsistencies between documentation and runtime behavior are real and can break integrations.
• These issues cause production bugs when request fields, response shapes, or naming assumptions are wrong.
• Use this document as a practical checklist to reduce avoidable integration failures.

Guiding Principle

• Treat runtime API behavior as the source of truth for implementation decisions.
• Use documentation to guide development, then confirm with real responses before release.

Naming Inconsistencies

• `customerId` vs `customer_id` appears across different endpoints.
• Branch identifiers are mixed across API surfaces: `branch_id`, `branch_code`, and `branch_num`.
• Naming patterns are not fully standardized (`id` vs `num` vs `code`, mixed casing styles).

Short example:

• One endpoint may expect `customer_id` while another uses `customerId` for a similar concept.

Request Field Inconsistencies

• Appointment create payload has a required-field mismatch: `customer_num` and `branch_num` are listed as required, while the same model defines alternates like `customer_id`, `branch_id`, `branch_code`, and `branch_name`, and does not define a `branch_num` property. [Needs Juvonno confirmation]
• Required vs optional expectations may need runtime verification before release.

Short example:

• Build flexible payload construction and validation so required or alternate fields can be selected per endpoint.

Response Shape Differences

• Some endpoints return arrays directly.
• Some return wrapped payloads with `total`, `page`, `count`, and `list`.
• Some return wrapped payloads with different keys (for example `count` and `data`).
• Some return a single object for one resource.

Short example:

• Do not hardcode one parser for all list endpoints.
• Inspect real responses for each endpoint before finalizing parser logic.

Pagination Inconsistencies

• Pagination is not fully standardized across endpoints.
• Common patterns include:
  • `page`
  • `start` + `results`
• Wrapper fields are commonly `total`, `page`, `count`, `list`, but not universal (for example some endpoints use `data`).

Short example:

• Implement endpoint-specific pagination adapters instead of one global assumption.

How to Handle These Safely

• Test each endpoint you plan to use before implementation is finalized.
• Parse responses defensively (support array, wrapped list, and single-object shapes where relevant).
• Do not rely only on endpoint summary/description text.
• Log and inspect response payloads during development.
• Add integration tests for identifier mapping and response-shape parsing.
• Normalize response handling in your integration layer so endpoint differences are handled in one place.

When to Escalate

• Endpoint behavior is clearly broken or contradictory.
• Required fields conflict in ways that block valid request construction.
• Validation failures occur for apparently valid inputs with no clear documentation.
• Runtime output consistently conflicts with documented contract in integration-critical flows.

Maintaining Your Own Notes

• Keep an internal known quirks tracker per endpoint your integration uses.
• Record:
  • expected request shape
  • accepted identifier fields
  • observed response format
  • known validation rules
• Update integration logic and tests when behavior changes.
• Re-verify critical endpoints after API updates.

Summary

• Treat runtime behavior as source of truth; documentation is guidance.
• Validate request fields and identifier types per endpoint before release.
• Build defensive parsers and normalize response handling in your integration layer.
• Keep internal endpoint notes and update them when behavior changes.