审查接口契约一致性与兼容性
比对接口运行行为、规范文档与客户端模型,定位字段、错误、版本和分页差异,并给出兼容性修复建议。
完整提示词
I want you to perform an ultra-deep, systematic, evidence-first, and client-oriented analysis of the complete API contract consistency across all endpoints, versions, clients, and runtime scenarios.
Main goal:
> Determine whether the API has a stable, predictable, and mutually consistent contract so that diverse clients can safely dispatch requests, parse responses, handle errors, and survive API evolution without hidden breaking changes.
This is not:
- a routine REST style audit
- just OpenAPI validation
- just a schema review
- advice that all responses must have the same envelope
- a demand that every endpoint looks identical
- automatic versioning introduction
- insistence on a single naming style without real client impact
- rewriting an API purely for aesthetics
Focus is on the actual contract that clients consume.
Priority:
**client correctness > backward compatibility > schema stability > error predictability > semantic consistency > documentation consistency > stylistic uniformity**
It is better to find 7 real contract mismatches than to write 100 stylistic recommendations.
---
# 1. IDENTIFY ALL CONTRACT SOURCES
Before findings, map out where the API contract is defined.
Possible sources:
- route/controller code
- request DTO
- response DTO
- validation schemas
- OpenAPI/Swagger
- generated types
- GraphQL schemas if present concurrently
- client SDK
- frontend/mobile types
- integration tests
- documentation
- API examples
- Postman collections
Do not assume documentation is the source of truth.
---
# 2. DETERMINE THE ACTUAL SOURCE OF TRUTH
For each contract component ask:
> What does runtime actually accept and return?
If they diverge:
```text
OpenAPI
vs
runtime validator
vs
actual serializer
```
document the drift.
---
# 3. CREATE CONTRACT INVENTORY
For each endpoint record:
```text
Method:
Path:
Request params:
Query:
Headers:
Body:
Success response:
Error responses:
Nullability:
Pagination:
Version:
Authentication:
```
---
# 4. CONTRACT MATRIX
Construct:
| Endpoint | Request schema | Response schema | Error schema | Versioned | Documented |
|---|---|---|---|---|---|
---
# 5. REQUEST NAMING
Compare field naming across the API.
Examples:
```text
userId
user_id
userid
userID
```
Do not report merely as styling.
Demonstrate real problems:
- client mapping
- generated SDK drift
- duplicated models
- user confusion
---
# 6. RESPONSE NAMING
Same for responses.
---
# 7. SAME CONCEPT, DIFFERENT NAME
Specifically look for the exact same domain concept under multiple names:
```text
createdAt
created
creationDate
dateCreated
```
---
# 8. SEMANTIC CONSISTENCY
The same name must convey the same meaning.
Example:
```text
status
```
in one endpoint means:
```text
HTTP-like lifecycle
```
and in another:
```text
payment status
```
This may be legitimate across different resources.
A finding requires actual ambiguity for the client model.
---
# 9. ID TYPES
Compare ID types:
```text
"id": 123
```
vs:
```text
"id": "123"
```
for the same resource.
---
# 10. UUID CONSISTENCY
If one endpoint returns a UUID string and another returns a numerical internal ID for the same entity:
check whether this is intentional.
---
# 11. PUBLIC VS INTERNAL ID
If the API uses:
- publicId
- internal DB ID
their boundary must remain distinct and well-defined.
---
# 12. DATE/TIME FORMAT
Map all temporal fields.
Search for:
```text
ISO 8601 string
epoch seconds
epoch millis
localized string
```
representing the same semantic type.
---
# 13. TIMEZONE
Timestamps must explicitly convey or imply timezone context.
Example:
```text
2026-09-25T20:00:00Z
```
is a completely different contract from:
```text
2026-09-25 20:00:00
```
without timezone context.
---
# 14. DATE-ONLY
Do not convert:
```text
birthday
```
into an instant if the domain represents strictly a calendar date.
---
# 15. EPOCH UNIT
If numeric timestamps are utilized:
verify that clients can unambiguously differentiate seconds and milliseconds.
---
# 16. MONEY FORMAT
Map:
```text
amount
currency
```
Verify:
- integer minor units
- decimal string
- float
for the same contract.
---
# 17. MONEY WITHOUT CURRENCY
If amount can represent multiple currencies, a value lacking currency context represents an incomplete contract.
---
# 18. BOOLEAN CONSISTENCY
Look for:
```text
true
false
```
vs:
```text
0
1
```
vs:
```text
"true"
"false"
```
for the exact same concept.
---
# 19. ENUM CONTRACT
Inventory enum values.
Example:
```text
PENDING
ACTIVE
FAILED
```
---
# 20. ENUM CASE
If the same enum concept employs:
```text
pending
PENDING
Pending
```
across different endpoints:
client complexity escalates.
---
# 21. UNKNOWN ENUM VALUE
Ask:
> What happens when backend adds a new value tomorrow?
Especially for mobile clients that may remain outdated for months.
---
# 22. OPEN ENUM VS CLOSED ENUM
Document whether the client should:
- reject unknown values
- present a fallback
- preserve the raw value
in accordance with the domain.
---
# 23. NULLABILITY
For each field distinguish:
```text
required non-null
required nullable
optional non-null
optional nullable
```
Do not treat these as equivalent states.
---
# 24. ABSENT VS NULL
Critical distinction:
```json
{}
```
is not necessarily identical to:
```json
{"name": null}
```
Especially in PATCH contracts.
---
# 25. EMPTY STRING VS NULL
If backend intermittently returns:
```text
""
```
and elsewhere:
```text
null
```
for "no value", examine client behavior.
---
# 26. EMPTY ARRAY VS NULL
Collection contract must be unambiguous.
Example:
```text
[]
```
is typically a different semantic signal than:
```text
null
```
---
# 27. MISSING COLLECTION
A third possible state:
field omitted entirely.
Verify whether clients expect this.
---
# 28. RESPONSE ENVELOPE
Inventory response structures.
Example:
```json
{"data": {...}}
```
vs:
```json
{"result": {...}}
```
vs direct object.
---
# 29. ENVELOPE IS NOT MANDATORY
Do not demand a uniform envelope purely for aesthetics.
A finding exists when inconsistency causes:
- generic client parsing issues
- SDK duplication
- error handling failures
---
# 30. LIST RESPONSE
Compare:
```json
[...]
```
with:
```json
{
"items": [...],
"total": 100
}
```
The divergence can be legitimate if one endpoint provides pagination.
---
# 31. PAGINATION CONTRACT
Map:
- page
- pageSize
- total
- nextCursor
- hasMore
- next
---
# 32. DIFFERENT PAGINATION MODELS
If one API uses:
```text
page/limit
```
another:
```text
offset/limit
```
and a third:
```text
cursor
```
this is not automatically a bug.
Ask whether the same resource family unnecessarily mixes multiple models.
---
# 33. PAGE NUMBER BASE
Verify:
```text
page starts at 0
```
vs:
```text
page starts at 1
```
---
# 34. LIMIT DEFAULT
Documentation and runtime must align.
---
# 35. MAX LIMIT
If docs declare 100, while runtime allows 1000 or vice versa:
contract drift.
---
# 36. TOTAL SEMANTICS
`total` can indicate:
- total items overall
- total returned
- filtered total
Must be unambiguous.
---
# 37. HASMORE
If computed inconsistently with nextCursor:
client pagination can stall or loop.
---
# 38. SORT CONTRACT
Map:
```text
sort
order
sortBy
sortDirection
```
---
# 39. SAME FILTER DIFFERENT PARAM
If the same endpoint family uses:
```text
status
filterStatus
state
```
for the same concept, examine the necessity.
---
# 40. CASE SENSITIVITY
Search/filter enum queries can be case-sensitive or insensitive.
Document actual behavior.
---
# 41. ARRAY QUERY PARAMS
Verify format:
```text
?status=a&status=b
```
vs:
```text
?status=a,b
```
vs JSON-like encoding.
---
# 42. BOOLEAN QUERY
Does the API accept:
```text
true
false
1
0
```
and what is documented?
---
# 43. DEFAULT FILTER
If omitted filter assumes different semantics across versions:
breaking semantic change.
---
# 44. REQUEST DTO
Compare create and update DTOs.
---
# 45. CREATE VS UPDATE
A field required upon creation may need to be optional during PATCH.
Do not reuse identical schema models blindly if semantics diverge.
---
# 46. IMMUTABLE FIELD
A field settable only upon creation:
```text
ownerId
type
```
must not accidentally be updateable.
---
# 47. SERVER-GENERATED FIELD
Clients must not be forced to provide:
- createdAt
- internal ID
- computed status
if the server generates them.
---
# 48. READ-ONLY FIELD IN REQUEST
If schema accepts yet silently ignores it:
client may falsely believe it modified the attribute.
It is better to explicitly reject or clearly document, according to contract rules.
---
# 49. WRITE-ONLY FIELD
Passwords must remain request-only and never appear as response fields.
Verify schema and documentation.
---
# 50. SENSITIVE RESPONSE FIELD
DTO reuse can accidentally expose:
- password hashes
- reset tokens
- secrets
- internal notes
---
# 51. ERROR SHAPE
Inventory all error shapes.
Example:
```json
{"error":"Not found"}
```
vs:
```json
{"message":"Not found"}
```
vs:
```json
{
"error": {
"code": "NOT_FOUND",
"message": "..."
}
}
```
---
# 52. SAME ERROR, DIFFERENT SHAPE
If a client must maintain multiple parsers for the same backend:
contract consistency problem.
---
# 53. ERROR CODE TYPE
Look for:
```text
"NOT_FOUND"
```
vs:
```text
40401
```
for the same error namespace.
---
# 54. ERROR CODE STABILITY
Human messages must not serve as machine identifiers.
---
# 55. FIELD VALIDATION ERRORS
Verify format.
Example:
```json
{
"fields": {
"email": ["invalid"]
}
}
```
or:
```json
{
"errors": [
{"field":"email","code":"INVALID"}
]
}
```
Stability is what matters.
---
# 56. FIELD PATH
Nested validation must provide a sufficiently precise path.
---
# 57. ARRAY VALIDATION
Example:
```text
items[3].price
```
must be unambiguously identifiable.
---
# 58. GLOBAL ERROR
Not every validation error belongs to a single field.
The API must be capable of expressing cross-field errors.
---
# 59. CORRELATION ID
If error responses include a request or correlation ID:
verify consistency.
---
# 60. HTTP STATUS + ERROR CODE
The same logical error should pair consistently wherever possible.
---
# 61. AUTH ERRORS
Compare:
- missing token
- expired token
- invalid token
- revoked token
- insufficient role
---
# 62. LOGIN ERRORS
Security intentionally homogenizes:
```text
wrong password
unknown email
```
to avoid exposing account existence.
Do not "fix" this into granular error messages without considering the threat model.
---
# 63. NOT FOUND
Private resources may intentionally return 404 instead of 403.
Consistency is evaluated within the specific security model, not by academic rules.
---
# 64. CONFLICT ERRORS
For duplicate creation or resource state conflicts, verify stable error codes.
---
# 65. RATE LIMIT ERRORS
If 429 exists:
verify:
- body
- retry hint
- headers
---
# 66. UPSTREAM ERROR
Do not forward raw provider error formats directly to clients if the rest of the API maintains a stable internal contract.
---
# 67. EXTERNAL PROVIDER LEAK
If Stripe, AWS, or other third-party provider payloads leak directly through an endpoint:
clients become tightly coupled to the upstream provider contract.
---
# 68. CONTRACT BOUNDARY
The backend must deliberately determine which external provider details are exposed.
---
# 69. SUCCESS STATUS SHAPE
Some endpoints return:
```json
{"success": true}
```
while others return a resource.
Ask whether clients truly require uniformity here.
---
# 70. COMMAND RESPONSE
Business commands like cancel may legitimately return:
```text
updated resource
```
or:
```text
204
```
What matters is that the contract is stable.
---
# 71. CREATE RESPONSE
Verify that create responses do not return a different object shape than subsequent GET requests for the same resource without reason.
---
# 72. CREATE/GET MODEL DRIFT
Example:
```text
POST /users -> {userId,name}
GET /users/:id -> {id,fullName}
```
For the same resource, this is high-signal inconsistency.
---
# 73. UPDATE RESPONSE
If PATCH returns only mutated fields while clients expect a complete resource representation:
document the contract clearly.
---
# 74. DELETE RESPONSE
Consistency within the resource family.
---
# 75. NESTED RESOURCE SHAPE
A user embedded inside an Order response may provide a smaller projection than the standalone User endpoint.
This is completely legitimate.
Do not demand full DTO representations everywhere.
---
# 76. PROJECTION TYPES
If there exist:
- UserSummary
- UserDetails
- UserAdminView
make the contract distinctions explicit.
---
# 77. SAME NAME, DIFFERENT SHAPE
The most dangerous scenario is when both responses claim to be:
```text
User
```
yet possess fundamentally divergent required fields.
---
# 78. GRAPH NORMALIZATION
If clients use normalized caches, stable IDs and typename/resource identity become essential.
Tie findings directly to the active client stack.
---
# 79. BOOLEAN FLAGS
Look for logical contradictions:
```json
{
"isActive": true,
"status": "DISABLED"
}
```
If both express the same concept, the contract allows impossible states.
---
# 80. REDUNDANT FIELDS
Duplicate representations can drift over time.
Example:
```text
fullName
firstName
lastName
```
is not automatically an issue, but identify which field acts as the source of truth.
---
# 81. COMPUTED FIELD
If server returns computed values, clients should not necessarily be forced to reconstruct them independently.
---
# 82. STALE COMPUTED FIELD
If computed fields and source fields derive from divergent snapshots:
inconsistency.
---
# 83. DEFAULT VALUES
Determine where defaults are applied:
- validator
- controller
- DB
- serializer
---
# 84. MULTIPLE DEFAULTS
If an omitted request field receives:
```text
false
```
in the validator, but the DB default is:
```text
true
```
different write paths can produce divergent results.
---
# 85. VERSIONING
Map all API versions.
---
# 86. SAME RESOURCE ACROSS VERSIONS
For:
```text
/v1/users
/v2/users
```
compare:
- field names
- type
- nullability
- semantics
- errors
---
# 87. BREAKING CHANGES
Classify:
```text
FIELD REMOVAL
FIELD RENAME
TYPE CHANGE
NULLABILITY CHANGE
SEMANTIC CHANGE
ENUM CHANGE
STATUS CHANGE
ERROR CHANGE
```
---
# 88. NULLABILITY BREAK
Field:
```text
string
```
becoming:
```text
string | null
```
can break strict typed clients.
---
# 89. OPTIONAL -> REQUIRED
Breaking request change.
---
# 90. REQUIRED -> OPTIONAL
Usually more compatible, but client semantics may alter.
---
# 91. NUMBER -> STRING
Frequent breaking change for IDs and monetary amounts.
---
# 92. ARRAY -> OBJECT
Clear breaking change.
---
# 93. OBJECT -> NULLABLE OBJECT
Potentially breaking.
---
# 94. ENUM ADDITION
Can break clients utilizing exhaustive enum parsers.
---
# 95. ENUM REMOVAL
Clear breaking semantic change for clients submitting the retired value.
---
# 96. FIELD SEMANTICS CHANGE
Most dangerous silent break.
Example:
```text
price
```
was in:
```text
dollars
```
and changes to:
```text
cents
```
without altering the data type.
---
# 97. UNIT CONTRACT
Map units:
- bytes
- KB
- MB
- seconds
- milliseconds
- meters
- kilometers
- percentages
---
# 98. PERCENT
Does:
```text
0.25
```
mean 25% or:
```text
25
```
?
---
# 99. FILE SIZE
Consistent unit representation.
---
# 100. DURATION
Do not mix:
```text
durationMs
```
with generic:
```text
duration
```
unless clearly specified.
---
# 101. COORDINATES
Latitude and longitude type and range consistency.
---
# 102. COUNTRY / LOCALE
Map:
- ISO code
- display name
- locale tag
Do not mix without an explicit contract.
---
# 103. LANGUAGE
Example:
```text
en
en-US
English
```
can represent three completely distinct contracts.
---
# 104. PHONE NUMBERS
If backend receives or returns phone numbers:
verify canonical vs display format.
---
# 105. EMAIL
Case normalization and canonicalization must not mutate contracts implicitly without understanding identity semantics.
---
# 106. URLS
Does the backend return:
- relative path
- absolute URL
- signed URL
for the same field across different endpoints?
---
# 107. SIGNED URL
Expiry semantics must be clear.
Clients must never assume signed URLs are permanent.
---
# 108. FILE OBJECT
If one endpoint returns:
```text
fileUrl
```
and another returns:
```json
{
"file": {
"url": "...",
"size": ...
}
}
```
verify whether these truly represent projections of the same resource.
---
# 109. MAP / DICTIONARY
Dynamic object keys can complicate typed clients.
Use only when the domain truly represents a map.
---
# 110. TUPLE-LIKE ARRAYS
Responses like:
```json
["123","John",true]
```
are fragile when positional indexes imply schema semantics.
High-signal finding for public APIs.
---
# 111. POLYMORPHISM
If a response can assume multiple types:
a discriminator or other reliable parsing mechanism must exist.
---
# 112. DISCRIMINATOR
Example:
```json
{"type":"image", ...}
```
Verify that each variant exhibits a stable contract.
---
# 113. UNKNOWN VARIANT
Older clients must have defined fallback behavior.
---
# 114. PAGINATION + POLYMORPHISM
If a paginated list contains diverse item kinds, typed clients need to know.
---
# 115. GENERIC `any`
If OpenAPI or TypeScript definitions specify `any` for critical responses:
the contract is insufficiently specified.
Severity (P4 vs P2) depends on client failure modes.
---
# 116. RAW JSON
`Map<String,Any>` or raw JSON can be legitimate for metadata extension fields.
Do not force rigid schemas everywhere.
---
# 117. EXTENSIBILITY
If API permits arbitrary metadata:
clearly segregate core stable fields from extension areas.
---
# 118. HEADER CONTRACT
Map custom headers:
- request ID
- idempotency key
- version
- tenant
- locale
---
# 119. HEADER CASING
HTTP header names are case-insensitive.
Do not build custom parsers that rely on casing.
---
# 120. REQUIRED HEADER
If an endpoint mandates a custom header:
it must be documented and validated.
---
# 121. TENANT HEADER
If tenant is supplied via a header:
authorization must bind it securely to the principal.
Contract consistency is not a replacement for security.
---
# 122. CONTENT TYPE
Map:
```text
application/json
multipart/form-data
application/octet-stream
```
---
# 123. ACCEPT HEADER
If the API supports multiple representations or versioning via media types:
verify consistency.
---
# 124. CHARACTER ENCODING
JSON must reliably support Unicode.
Search for manual encoding flaws.
---
# 125. EMPTY RESPONSE
Distinguish:
- 204
- 200 {}
- 200 null
within the contract.
---
# 126. OPTIONAL RESPONSE
An endpoint that legitimately can find nothing must have a documented model.
---
# 127. SEARCH SINGLE RESULT
Never return an object sometimes and an array other times for the exact same endpoint.
---
# 128. ONE-OR-MANY
Contracts like:
```text
object | array
```
lacking a clear discriminator represent high risk for typed clients.
---
# 129. REQUEST COERCION
Validators may coerce:
```text
"123"
```
into:
```text
123
```
Document the actual accepted contract.
---
# 130. STRICT VS COERCED TYPES
If one endpoint coerces query numbers while another rejects them:
this can indicate client inconsistency.
---
# 131. TRIM
Does the backend trim whitespace?
If divergent endpoints handle the same field differently, semantic bugs can emerge.
---
# 132. CASE NORMALIZATION
Same for usernames and codes.
---
# 133. INPUT NORMALIZATION
Map:
```text
raw input
↓
normalized domain value
```
---
# 134. RESPONSE NORMALIZATION
If a client sends:
```text
" John "
```
and the response returns:
```text
"John"
```
this can be legitimate, but should be expected.
---
# 135. VALIDATION BOUNDS
Compare constraints on the same field across create, update, and bulk endpoints.
---
# 136. DUPLICATE SCHEMAS
If copy-pasted schemas drifted apart:
pinpoint concrete differences.
---
# 137. GENERATED SCHEMA
If OpenAPI is generated from DTOs:
verify that runtime transforms and interceptors do not mutate the response outside the schema.
---
# 138. SERIALIZER TRANSFORM
A global serializer may:
- rename fields
- strip nulls
- transform dates
OpenAPI must reflect the actual serialized outcome.
---
# 139. NULL EXCLUSION
If the serializer omits null fields:
spec must not falsely claim the field is always present with null.
---
# 140. DEFAULT EXCLUSION
Same for default values.
---
# 141. ORM SERIALIZATION
Direct ORM serialization can return:
- Decimal objects
- Dates
- relation proxies
diverging from the promised DTO contract.
---
# 142. BIGINT SERIALIZATION
Especially Node.js:
native BigInt is not natively JSON-serializable without custom transformations.
Verify the active runtime layer.
---
# 143. DECIMAL SERIALIZATION
ORM Decimal can become a string.
The spec and client must align.
---
# 144. BINARY DATA
Do not embed massive binaries directly into base64 JSON without reason.
However, small encoded fields may be legitimate.
---
# 145. OPENAPI AUDIT
If spec exists:
compare:
- paths
- methods
- params
- request
- response
- errors
- auth
- enum
- required
- nullable
---
# 146. STALE OPENAPI
Documentation generated months ago does not prove the runtime contract.
---
# 147. DOCUMENTATION EXAMPLES
Example payloads can drift even when schema remains accurate.
---
# 148. COPY-PASTE DOC BUG
Identify examples illustrating mismatched resource fields.
---
# 149. CLIENT SDK
If repository houses a client SDK:
compare SDK models against backend contracts.
---
# 150. GENERATED CLIENT
If SDK is generated from OpenAPI:
OpenAPI drift directly translates into client bugs.
---
# 151. MANUAL CLIENT TYPES
Frontend and mobile codebases often maintain handcrafted DTO types.
Compare them.
---
# 152. CLIENT NULLABILITY
Backend may return null while client type declares non-null.
Severity P1/P2 if normal runtime conditions trigger this.
---
# 153. CLIENT OPTIONALITY
Backend may omit a field that client logic treats as required.
---
# 154. CLIENT ENUM
Backend adds a new enum value while client enum is closed.
---
# 155. CLIENT DATE PARSER
Backend alters date format, causing client parsers to crash.
---
# 156. CLIENT NUMBER PRECISION
JS clients can lose precision on 64-bit numeric IDs.
If API emits large integer IDs as JSON numbers, verify the actual numeric range.
---
# 157. MULTIPLE CLIENTS
If there are:
- web
- Android
- iOS
- third-party APIs
map every contract consumer.
---
# 158. CLIENT CAPABILITY MATRIX
Construct:
| Contract feature | Web | Android | iOS | External |
|---|---|---|---|---|
---
# 159. SERVER CHANGE IMPACT
For each breaking candidate ask:
> Which clients are impacted?
---
# 160. MOBILE LAG
Mobile application updates are never instantaneous.
Backend must tolerate older releases across the full supported lifecycle.
---
# 161. WEB CLIENT
Web apps deploy faster, but cached browser tabs and service workers can temporarily consume stale contracts.
---
# 162. THIRD-PARTY CLIENT
If a public API serves external integrators:
backward compatibility increases dramatically in criticality.
---
# 163. CONTRACT VERSIONING
Versioning can be implemented via:
- path
- header
- media type
- schema version field
Do not mandate a single pattern.
---
# 164. VERSION NEGOTIATION
If a client requests an unsupported version:
the response must be deterministic and clear.
---
# 165. VERSION DEFAULT
If omitting version defaults to "latest", this can spontaneously break older clients.
Verify the versioning resolution model.
---
# 166. SUNSET
If API supplies deprecation and sunset headers:
verify consistency.
P4 unless mandated by product requirements.
---
# 167. FEATURE FLAGS
A flag altering response shapes for a subset of users can severely complicate client contracts.
---
# 168. CONDITIONAL FIELD
If a field exists only when a feature flag is active:
the spec must explicitly model it or mark the field optional.
---
# 169. ROLE-DEPENDENT SHAPE
Admin responses may expose additional fields.
Do not declare them under the same strict schema model if regular users receive a subset.
---
# 170. PERMISSION-DEPENDENT FIELD
Same.
---
# 171. EXPANSION PARAMETER
If endpoint supports:
```text
?expand=owner
```
verify that the schema clearly describes the optional expanded entity.
---
# 172. SPARSE FIELDSETS
If `fields=` parameter is supported, evaluate typed client parsing consequences.
---
# 173. LOCALIZATION
If response fields vary content based on locale:
types remain stable, but cache keys and documentation must reflect localization.
---
# 174. TRANSLATED ENUM LABEL
Do not conflate stable machine enum codes with localized display labels.
---
# 175. SERVER MESSAGE
Human-readable messages may be localized.
Clients must never bind business logic to message text.
---
# 176. BULK ENDPOINT
Bulk response contracts must reliably map inputs to corresponding outputs.
---
# 177. INDEX-BASED BULK RESULT
If results rely solely on array order:
verify that backend strictly guarantees ordered processing.
---
# 178. PER-ITEM ID
A more resilient mapping utilizes an input or client operation ID.
Do not demand without necessity, but flag ambiguity.
---
# 179. PARTIAL FAILURE
Bulk responses must clearly communicate:
- successes
- failures
- per-item details
---
# 180. ALL-OR-NOTHING
If batch execution is atomic, the contract must explicitly state so.
---
# 181. ASYNC CONTRACT
The 202/job model requires a stable Job resource schema.
---
# 182. JOB STATUS ENUM
Verify:
- pending
- running
- completed
- failed
- cancelled
and client handling of unobserved states.
---
# 183. PROGRESS
If progress reporting exists:
clearly define whether range is:
```text
0..1
```
or:
```text
0..100
```
---
# 184. RESULT
Completed jobs must possess a defined result object or resource link.
---
# 185. FAILURE
Async job error contracts should be parsable like sync API errors or follow a dedicated, well-documented model.
---
# 186. WEBHOOK CONTRACT
If backend dispatches webhooks:
analyze them as public contracts.
---
# 187. WEBHOOK VERSIONING
Provider-side event schemas can evolve independently from REST responses.
---
# 188. EVENT TYPE
Stable event types:
```text
order.created
```
must convey unambiguous semantics.
---
# 189. EVENT PAYLOAD
Whether payloads contain:
- full resource
- delta
- ID only
must be explicit.
---
# 190. EVENT SCHEMA DRIFT
If webhook documentation and spec diverge from runtime payloads:
integration break.
---
# 191. DUPLICATE EVENTS
While deduplication is a reliability topic, contracts must provide stable event IDs if consumers must dedup.
---
# 192. EVENT TIME
Differentiate:
- event occurred
- webhook delivered
timestamp semantics.
---
# 193. IMPORT/EXPORT CONTRACT
If export formats serve as data or API contracts:
versioning becomes crucial.
---
# 194. CSV
Verify:
- headers
- encoding
- delimiter
- escaping
only where CSV constitutes part of the product contract.
---
# 195. JSON EXPORT
Version fields may be needed if exports are subsequently re-imported.
---
# 196. ROUNDTRIP
Export -> import must preserve semantic data promised by the product.
---
# 197. GRAPHQL INTEROP
If backend provides both REST and GraphQL:
compare domain semantics.
Do not mandate identical response shapes.
---
# 198. DUPLICATE DOMAIN ENUM
REST and GraphQL must not assign divergent meanings to the same status without clear reason.
---
# 199. INTERNAL API
Internal APIs also possess contracts if other services consume them.
---
# 200. SERVICE-TO-SERVICE
A breaking contract change can take down downstream microservices even if the public frontend remains functional.
---
# 201. MESSAGE QUEUE CONTRACT
If event payloads act as inter-service contracts, audit them.
---
# 202. EVENT VERSION
If consumers deploy independently, schema evolution rules are critical.
---
# 203. REMOVE FIELD
Older consumers may still depend on the removed attribute.
---
# 204. ADD REQUIRED FIELD
Consumer deserializers may fail.
---
# 205. SCHEMA REGISTRY
If a schema registry is present, check compatibility settings.
If not:
do not demand one automatically.
---
# 206. CONTRACT TESTS
Map:
- API integration
- schema validation
- snapshot
- generated SDK
- consumer-driven contracts
---
# 207. SNAPSHOT TEST
Snapshots can catch accidental response mutations.
However, they become fragile if covering non-deterministic fields.
---
# 208. SCHEMA TEST
Validating runtime responses against OpenAPI schemas provides strong signals.
---
# 209. CONSUMER-DRIVEN CONTRACT
If multiple independent teams or services consume the API, consumer-driven contracts add high value.
Do not introduce without cause.
---
# 210. GOLDEN PAYLOADS
Critical contracts benefit from golden payload fixtures.
---
# 211. OLD CLIENT TEST
Run older client models and parsers against the new backend responses where feasible.
---
# 212. UNKNOWN FIELD TEST
Clients should generally ignore unknown response fields.
Verify actual serializers and parsers.
---
# 213. UNKNOWN ENUM TEST
Especially on mobile platforms.
---
# 214. NULL TEST
Backend fixtures populated with realistic null values.
---
# 215. OMITTED FIELD TEST
Same for omitted attributes.
---
# 216. MAX VALUE TEST
Boundary values for IDs, counts, and amounts.
---
# 217. LARGE INTEGER TEST
Specifically web/JS runtimes.
---
# 218. DATE EDGE TEST
- UTC
- timezone offset
- DST
- leap day
according to domain.
---
# 219. DECIMAL TEST
Precision-sensitive fields.
---
# 220. BULK MIXED RESULT TEST
Batches containing both successful and failing items.
---
# 221. FINDING FORMAT
Every serious finding must include:
```text
ID:
Severity:
Category:
Confidence:
Evidence tier:
Status:
Endpoint/Event:
Method:
Version:
Affected client(s):
Backend file/schema:
Client file/schema:
OpenAPI/documentation:
Relevant definitions:
Problem:
Evidence:
Contract Comparison:
Expected:
Actual:
Runtime example:
Backward compatibility impact:
Client failure mode:
Data/semantic impact:
Root cause:
Recommended remediation:
Migration/compatibility strategy:
Regression/contract test:
Verification:
Complexity:
XS / S / M / L / XL
```
---
# 222. SEVERITY
Use:
## P0 - CRITICAL
- contract inconsistency triggers cross-user or security boundary failure
- financial or data corruption due to unit/type mismatch
- catastrophic consumer misinterpretation
## P1 - HIGH
- released client routinely crashes or cannot execute critical API flows
- silent semantic mismatch corrupts critical business data
- normal response violates declared non-null or type contract
- production versioning change breaks supported clients
## P2 - MEDIUM
- significant schema, error, or pagination inconsistency with real client impact
- response drift requiring substantial client workarounds
## P3 - LOW
- limited inconsistency
- edge-case parsing problem
## P4 - IMPROVEMENT
- naming, style, or documentation harmonization without confirmed runtime failure
---
# 223. CONFIDENCE
Use:
```text
HIGH
MEDIUM
LOW
```
HIGH:
backend and consumer definitions directly conflict, or a test reproduces the issue.
MEDIUM:
runtime schema is clear, but affected client behavior is not completely confirmed.
LOW:
depends on external clients or undocumented consumer behavior.
---
# 224. EVIDENCE MODEL
Assign every finding an evidence tier:
```text
A - reproduced: a contract test, a real request/response or a client run shows the mismatch
B - complete static path: runtime handler, validator, serializer and the client parser or type are all read and conflict
C - strong static evidence: one side is clear, the other side (client, version, role projection) is partly unverified
D - inference: depends on external or undocumented consumers, or on runtime configuration not seen
E - harmonization: naming, style or documentation improvement without a runtime failure
```
Tiers map to the other fields:
- CONFIRMED requires tier A or B.
- LIKELY is tier C.
- THEORETICAL and NOT VERIFIED are tier D.
- Tier E findings are P4 and are never reported as breaking.
Documentation or OpenAPI alone is at most tier C; it must be compared with the runtime handler and serializer before a finding is CONFIRMED.
---
# 225. STATUS
Use:
```text
CONFIRMED
LIKELY
THEORETICAL
NOT VERIFIED
```
---
# 226. COMPATIBILITY CLASS
For each contract change classify:
```text
BACKWARD COMPATIBLE
POTENTIALLY BREAKING
BREAKING
SEMANTICALLY BREAKING
NOT VERIFIED
```
---
# 227. AFFECTED CLIENT
Use:
```text
WEB
ANDROID
IOS
EXTERNAL
SERVICE
WEBHOOK CONSUMER
ALL
UNKNOWN
```
---
# 228. FALSE-POSITIVE PREVENTION
Before any P1/P2 finding, verify:
1. runtime handler
2. validator
3. serializer
4. DTO/schema
5. OpenAPI
6. client parser/types
7. version
8. tests
9. feature flags
10. role-specific projections
Do not conclude solely from documentation.
---
# 229. DO NOT ENFORCE IDENTICAL DTOS
Summary and Detail resources can legitimately exhibit different shapes.
Report a finding only if contract identity or typing becomes ambiguous.
---
# 230. DO NOT ENFORCE A SINGLE ERROR MESSAGE
Human-readable text may vary.
Machine-readable semantics must be stable where client logic depends on them.
---
# 231. DO NOT ENFORCE ENVELOPE
Direct response representations can form excellent contracts.
---
# 232. DO NOT ENFORCE VERSIONING
If compatibility requirements do not exist, versioning adds complexity without benefit.
---
# 233. DO NOT RENAME FIELDS PURELY FOR AESTHETICS
Renaming a public field is a breaking change.
Minor naming inconsistencies are preferable to breaking production clients.
---
# 234. BACKWARD COMPATIBILITY TAKES PRECEDENCE OVER ELEGANCE
If an existing "imperfect" schema serves clients in production:
do not refactor it without a comprehensive migration and versioning strategy.
---
# 235. DO NOT MODIFY CODE
During audit:
- do not rename fields
- do not change schemas
- do not introduce envelopes
- do not add versioning
- do not change errors
- do not alter enums
Finish the audit first.
---
# 236. OUTPUT - API_CONTRACT_CONSISTENCY_AUDIT.md
Structure the final report:
## 1. Executive Summary
- contract sources
- API versions
- clients
- primary consistency problems
- compatibility readiness
## 2. Contract Source-of-Truth Map
## 3. Endpoint Contract Inventory
## 4. Naming Consistency
## 5. Primitive Type Consistency
## 6. ID Contract Audit
## 7. Date / Time Contract Audit
## 8. Money / Decimal / Unit Audit
## 9. Nullability / Optionality Audit
## 10. Enum Audit
## 11. Request DTO Consistency
## 12. Response DTO Consistency
## 13. Error Contract Consistency
## 14. Pagination Contract Audit
## 15. Filter / Sort Contract Audit
## 16. Header Contract Audit
## 17. Async Job Contract Audit
## 18. Bulk Contract Audit
## 19. Webhook / Event Contract Audit
## 20. OpenAPI Drift Audit
## 21. Client Type Drift Audit
## 22. Multi-Client Compatibility
## 23. Versioning / Backward Compatibility
## 24. Contract Test Coverage
## 25. Findings Summary
| ID | Severity | Contract | Client | Problem | Compatibility | Status |
|---|---|---|---|---|---|---|
## 26. P0 Findings
## 27. P1 Findings
## 28. P2 Findings
## 29. P3 Findings
## 30. P4 Improvements
## 31. Things Done Well
## 32. Unknown / Not Verified
## 33. Compatibility Remediation Roadmap
---
# 237. FIELD CONSISTENCY MATRIX
For shared concepts:
| Concept | Endpoint A | Endpoint B | Client model | Consistent |
|---|---|---|---|---|
---
# 238. NULLABILITY MATRIX
| Field | Runtime | OpenAPI | Web | Mobile | Risk |
|---|---|---|---|---|---|
---
# 239. ENUM MATRIX
| Enum | Backend | Web | Mobile | Unknown-safe | Risk |
|---|---|---|---|---|---|
---
# 240. ERROR MATRIX
| Logical error | HTTP | Error code | Shape | Endpoints | Consistent |
|---|---|---|---|---|---|
---
# 241. PAGINATION MATRIX
| Endpoint | Model | Index base | Max | Ordering | Consistent |
|---|---|---|---|---|---|
---
# 242. VERSION MATRIX
| Contract change | Old version | New version | Client impact | Classification |
|---|---|---|---|---|
---
# 243. SECOND PASS - SAME CONCEPT SEARCH
After the initial audit, select core domain concepts:
- user
- status
- amount
- date
- ID
- pagination
- error
and search repository-wide for all representations.
Ask:
> Does the same concept consistently carry the same meaning?
---
# 244. SECOND PASS - NULL ATTACK
For each optional or nullable field test:
```text
missing
null
empty string
empty array
```
according to type.
Verify both backend and clients.
---
# 245. SECOND PASS - UNKNOWN ENUM
Backend emits a new enum value unknown to the released mobile client.
Ask:
> Does the client crash, reject the response, or execute a graceful fallback?
---
# 246. SECOND PASS - OLD CLIENT
For each newer contract change simulate the previously supported client version.
---
# 247. SECOND PASS - TYPE EDGE
Test:
- large int
- decimal precision
- zero
- negative
- max values
according to domain.
---
# 248. SECOND PASS - DATE EDGE
Test:
```text
UTC
+14:00
-12:00
DST transition
leap day
```
where relevant.
---
# 249. SECOND PASS - PAGINATION
Seed multiple items with identical sort values.
Verify deterministic, stable ordering.
---
# 250. SECOND PASS - ERROR DRIFT
Trigger the same logical failure across multiple endpoints.
Compare:
- HTTP status
- code
- shape
- field path
---
# 251. SECOND PASS - OPENAPI
Automatically or manually compare each critical runtime response with the declared schema.
---
# 252. SECOND PASS - ROLE VARIANTS
Invoke the same endpoint as:
- ordinary user
- admin
- owner
- non-owner
where relevant.
Verify response shape remains within the documented contract.
---
# 253. SECOND PASS - FEATURE FLAGS
If flags influence responses:
test both enabled and disabled states.
---
# 254. SECOND PASS - BULK
Mixed success and failure payload.
Ask whether clients can deterministically correlate results with inputs.
---
# 255. SECOND PASS - WEBHOOK
Compare webhook and event schemas with corresponding REST resources.
They do not need to be identical, but semantics must align clearly.
---
# 256. SECOND PASS - DOC EXAMPLES
Validate each example payload against the actual runtime schema.
---
# 257. FINAL QUALITY GATE
Before final response verify:
- runtime contract takes precedence over documentation assumptions
- the same domain concept is mapped repository-wide
- ID types are compared
- timestamps and timezone semantics are verified
- money and unit representations are not implicitly conflated
- null, missing, and empty values are not treated as equivalent
- create and update schemas have appropriate optionality semantics
- read-only and sensitive fields are not accidentally writeable or readable
- enum evolution is analyzed for legacy clients
- error messages are not treated as stable machine identifiers
- pagination indexing, defaults, and ordering are audited
- response summary and detail projections are not falsely labeled as inconsistencies
- OpenAPI is compared against runtime behavior
- manual client types are compared where present
- older mobile clients are evaluated where compatibility matters
- feature-flagged and role-dependent response shapes are accounted for
- breaking changes and stylistic variations are clearly separated
- public field renames are never recommended purely for styling
- backward compatibility is strictly prioritized over aesthetics
---
# FINAL RULE
I do not want a report like:
> Standardize naming, use OpenAPI, and align response structures.
That is not a contract audit.
I am looking for problems like:
```text
POST /orders response:
{
"id": 123
}
GET /orders/123 response:
{
"id": "123"
}
↓
web client treats IDs as number
↓
mobile model expects String
↓
shared caching/comparison logic becomes inconsistent
```
or:
```text
OpenAPI:
email: string
Runtime:
email: string | null
Android generated model:
val email: String
↓
production user without email receives null
↓
client deserialization/runtime flow fails
```
or:
```text
API v1 status enum:
PENDING
ACTIVE
backend later adds:
SUSPENDED
old mobile client uses exhaustive enum parser
↓
unknown SUSPENDED value
↓
entire response fails to parse
```
or:
```text
PATCH /profile
missing "nickname"
means:
leave unchanged
but:
"nickname": null
is silently normalized to missing
↓
client has no way to clear nickname
```
or:
```text
GET /transactions
amount = "12.50"
GET /account/summary
balance = 12.5
POST /payment
amount = 1250
↓
same monetary concept uses decimal string,
floating number and minor units
↓
client can silently interpret one value incorrectly
```
or:
```text
API docs:
page starts at 1
runtime:
page=1 applies offset=limit
↓
first page is skipped
↓
generated/integrating client never receives first result set
```
or:
```text
backend error A:
{
"code": "INVALID_STATE"
}
same logical failure on bulk endpoint:
{
"message": "Cannot update item"
}
↓
client can recognize and handle conflict in one flow
but not in another
```
These are the API contract consistency problems you need to find.
Think through:
- same concept
- same type
- same semantics
- nullability
- enum evolution
- units
- errors
- versions
- documentation
- actual consumers
For each serious finding you must be able to answer:
> Which backend contract exists?
> Which client contract exists?
> Where do they diverge?
> Does the issue manifest today or only after schema evolution?
> Can the issue be resolved backward-compatibly or does it require versioning/migration?
If not provable:
**NOT VERIFIED.**
If it is merely a naming or style difference without runtime impact:
**P4 - IMPROVEMENT.**
If a "fix" itself would break existing clients:
do not recommend it without a compatibility plan.
It is better to find 7 real schema or semantic mismatches than to write 100 stylistic rules.
The goal is to produce a forensically precise API contract audit from which each serious finding can be directly converted into:
- contract test
- schema correction
- backward-compatible migration
- OpenAPI fix
- client model fix
- versioning decision
- compatibility safeguard可替换内容
- [...]
- ["invalid"]
- [3]
- ["123","John",true]
分类与标签
编程开发、API审计、接口兼容、OpenAPI、客户端集成