返回提示词目录第 1379 页

REST API安全与契约审计

从实际路由与代码行为出发检查接口契约、权限、校验和幂等性,定位可复现问题并提出验证和修复方案。

完整提示词

I want you to perform an ultra-deep, systematic, evidence-first, and production-oriented analysis of the complete REST API.

Main goal:

> Determine whether the API has consistent and secure contracts, correct HTTP semantics, clear validation, reliable authentication/authorization, deterministic error models, idempotent behavior where needed, stable versioning behavior, and strong compatibility with real-world clients and production conditions.

This is not:

- a generic REST best practices checklist
- automatic insistence on "REST purity"
- an attempt to turn every route into a textbook resource model
- insistence that everything must be `GET/POST/PUT/PATCH/DELETE` in perfect academic form
- automatic prohibition of RPC-like endpoints
- a superficial check of HTTP status codes
- just an OpenAPI review
- just a security audit

Focus is on real API behavior.

Priority:

**correctness > authorization > data integrity > contract stability > idempotency > error semantics > compatibility > elegance**

It is better to find 6 real API problems than to write 100 generic REST recommendations.

---

# 1. DETERMINE THE API STACK

Before findings, establish:

- framework
- routing system
- middleware
- validation library
- auth
- serialization
- ORM/repository
- OpenAPI/Swagger
- API versioning
- rate limiting
- pagination
- caching
- reverse proxy/API gateway
- tests

---

# 2. CREATE ROUTE INVENTORY

Find all REST routes.

For each record:

```text
Method:
Path:
Auth:
Authorization:
Request schema:
Response schema:
Status codes:
Side effects:
Idempotent:
Pagination:
Rate limit:
```

---

# 3. FINAL ROUTE TABLE

Produce:

| Method | Route | Auth | Authorization | Validation | Success | Main errors |
|---|---|---|---|---|---|---|

Do not rely only on documentation.

Code is the source of truth.

---

# 4. PATH SEMANTICS

Verify that path clearly represents:

- resource
- collection
- subresource
- operation

Examples:

```text
/users
/users/:id
/users/:id/sessions
```

However, an RPC-like route is not automatically a bug.

Example:

```text
/orders/:id/cancel
```

can be completely legitimate if it represents a business command.

---

# 5. RESOURCE IDENTITY

For each resource determine:

- primary ID
- public ID
- slug
- owner/tenant

Ask:

> Does the route stably identify the exact same logical resource?

---

# 6. GET SEMANTICS

GET should not have a business side effect.

Look for:

```text
GET /delete-user
GET /mark-paid
GET /send-email
```

If GET mutates state:

serious semantics/caching/security problem.

---

# 7. SAFE METHOD

If GET/HEAD can mutate durable state, a browser, crawler, cache, or prefetch mechanism may unexpectedly trigger the action.

---

# 8. POST

POST is legitimate for:

- create
- command
- non-idempotent operation

Do not force PUT where business semantics do not fit.

---

# 9. PUT

If PUT is used, verify that semantics represent replacement or idempotent update according to the API contract.

---

# 10. PATCH

Verify:

- partial update semantics
- omitted field
- explicit null
- field deletion

---

# 11. MISSING VS NULL

Critical contract question:

```json
{}
```

is not the same as:

```json
{"name": null}
```

if the API allows nullable fields.

---

# 12. DELETE

Verify behavior for:

- existing resource
- already deleted
- missing resource
- soft delete
- dependent resources

---

# 13. DELETE IDEMPOTENCY

Repeated DELETE must have well-defined behavior.

It does not have to return the same status code every time, but the final resource state must be stable.

---

# 14. HTTP STATUS CODES

Map actual usage:

- 200
- 201
- 202
- 204
- 400
- 401
- 403
- 404
- 409
- 422
- 429
- 500
- 502/503/504

Do not insist on one "sacred" status code where multiple models are legitimate.

---

# 15. 200 FOR ERROR

If an endpoint returns:

```json
{
  "success": false,
  "error": "..."
}
```

with 200 for normal failure semantics, inspect client impact.

---

# 16. 201 CREATED

For a create endpoint, verify whether the response clearly identifies the created resource.

---

# 17. 202 ACCEPTED

If the API returns 202:

it must be clear that the work is not yet finished.

Check how the client discovers the final result.

---

# 18. 204

204 must not have a meaningful response body.

Check actual framework behavior.

---

# 19. 400 VS 422

Do not waste audit time on an academic debate if the API is consistent.

What matters is a stable distinction between:

- malformed request
- validation/business rejection

---

# 20. 401 VS 403

Verify:

- 401 for missing/invalid authentication
- 403 for authenticated principal without permissions

where that matches the auth model.

---

# 21. RESOURCE EXISTENCE LEAK

Sometimes an API intentionally uses 404 even for an unauthorized resource to avoid leaking existence.

Do not blindfoldedly change that to 403.

---

# 22. 404

Verify that the endpoint does not return 200 + null for a missing resource if the client expects a normal resource.

However, a documented nullable lookup may be valid.

---

# 23. 409 CONFLICT

Relevant for:

- duplicate
- version conflict
- invalid state transition

Verify consistency.

---

# 24. 429

If rate limiting exists, verify the response contract and any Retry-After header.

---

# 25. 5XX

A server bug or upstream failure must not be presented as a user validation error.

---

# 26. RESPONSE BODY

For each endpoint verify stability of:

- field names
- types
- nullability
- nested structures

---

# 27. RESPONSE ENVELOPE

If the API uses:

```json
{"data": ...}
```

verify consistency.

Do not force an envelope if the API lacks one and clients work well.

---

# 28. METADATA

Pagination and metadata must have a stable shape.

---

# 29. ERROR MODEL

Ideally, every client-visible error has a stable machine-readable code.

Example:

```json
{
  "error": {
    "code": "EMAIL_ALREADY_EXISTS",
    "message": "..."
  }
}
```

It does not have to be exactly this structure.

---

# 30. ERROR MESSAGE AS CONTRACT

If client logic relies on:

```text
if message == "User not found"
```

that is a fragile contract.

---

# 31. ERROR CODE

A machine-readable code must be more stable than a human-readable message.

---

# 32. LOCALIZATION

Backend error messages do not necessarily need to be localized if the client relies on error codes and translates UI.

Verify actual architecture.

---

# 33. STACK TRACE LEAK

Production responses must never expose:

- stack traces
- SQL
- filesystem paths
- internal service details
- secrets

---

# 34. VALIDATION

Map all inputs:

- path params
- query params
- headers
- body
- multipart

---

# 35. PATH PARAM VALIDATION

If an endpoint expects UUID/int:

verify that invalid format is deterministically rejected.

---

# 36. QUERY PARAM VALIDATION

Especially:

- sort
- filter
- page
- limit
- date range
- search

---

# 37. BODY VALIDATION

Verify:

- required
- optional
- nullable
- enum
- min/max
- length
- nested arrays
- unknown fields

---

# 38. UNKNOWN FIELDS

Determine whether the API:

- ignores
- rejects

unknown fields.

Both models can be valid.

Security and stability are what matter.

---

# 39. MASS ASSIGNMENT

Critical:

```text
request body
↓
ORM update
```

without whitelisting.

Look for fields like:

- role
- ownerId
- isAdmin
- status
- balance

---

# 40. BUSINESS VALIDATION

Schema validation does not solve:

```text
start < end
amount <= allowed
state transition allowed
```

---

# 41. DUPLICATE VALIDATION

If the same business rule exists across multiple endpoints:

check for drift.

---

# 42. AUTHENTICATION INVENTORY

For each route classify:

```text
PUBLIC
AUTHENTICATED
ADMIN
SERVICE-TO-SERVICE
WEBHOOK
```

---

# 43. MISSING AUTH

Look for critical routes that are accidentally public.

---

# 44. AUTH MIDDLEWARE COVERAGE

Do not assume global middleware covers all route groups.

---

# 45. AUTHORIZATION

For each resource endpoint ask:

> Does the authenticated user have rights over THIS SPECIFIC resource?

---

# 46. IDOR

Classic flow:

```text
GET /documents/123
```

User must have authorization for document 123.

Not just a valid session.

---

# 47. UPDATE IDOR

Especially:

```text
PATCH /users/:id
```

Can a user modify someone else's ID?

---

# 48. DELETE IDOR

Same for delete.

---

# 49. NESTED RESOURCE AUTH

Example:

```text
/projects/:projectId/tasks/:taskId
```

Verify that task actually belongs to project and user has rights to project/task.

---

# 50. PARENT/CHILD MISMATCH

An endpoint might load a task only by `taskId`, ignoring `projectId`.

The route looks scoped, but authorization is not.

---

# 51. TENANT BOUNDARY

If multi-tenancy exists:

every query/write/cache must use tenant context.

---

# 52. TENANT ID FROM REQUEST

Client-provided tenant ID is not an authority.

It must be bound to the authenticated principal.

---

# 53. ADMIN ROUTES

Verify that having:

```text
/auth/admin/*
```

in the path name is not sufficient by itself.

Real role/capability verification must exist.

---

# 54. ROLE VS PERMISSION

If the system has granularity:

- role
- permission
- ownership

verify that the endpoint uses the proper level.

---

# 55. FIELD-LEVEL AUTHORIZATION

A user may be allowed to edit a resource, but not all fields.

Example:

- name yes
- ownerId no
- billingStatus no

---

# 56. RESPONSE FIELD AUTHORIZATION

The same resource may contain sensitive fields not meant for every caller.

---

# 57. AUTHORIZED WRITE, UNAUTHORIZED READ

Inspect asymmetric edge cases.

---

# 58. API VERSIONING

Determine whether there is:

- path version
- header version
- media type
- implicit unversioned API

---

# 59. VERSIONING IS NOT MANDATORY BY DEFAULT

A small internal API can legitimately be unversioned.

Severity depends on external client compatibility requirements.

---

# 60. BREAKING CHANGE

Identify:

- field rename
- type change
- enum removal
- endpoint removal
- semantics change

---

# 61. ADDITIVE CHANGE

Adding an optional response field is often backward-compatible.

However, strict client parsers can alter that reality.

---

# 62. ENUM EVOLUTION

A new enum value can break a client expecting an exhaustive list.

---

# 63. REQUIRED REQUEST FIELD

Adding a new required field can break older clients.

---

# 64. OLD CLIENT

For mobile/public APIs ask:

> Does the backend still work with a client that is several months old?

---

# 65. DEPRECATION

If an endpoint is being sunset:

verify plan and usage.

---

# 66. PAGINATION

For collection endpoints determine:

- offset
- cursor
- keyset
- none

---

# 67. UNBOUNDED COLLECTION

If a dataset can grow, an endpoint without limits can become a production risk.

---

# 68. LIMIT BOUNDS

Client must not be allowed to request:

```text
limit=10000000
```

if that can exhaust backend resources.

---

# 69. NEGATIVE PAGE/LIMIT

Validation.

---

# 70. STABLE ORDERING

Pagination requires deterministic ordering.

---

# 71. OFFSET PAGINATION

If data changes between page requests:

there may arise:

- duplicates
- missing items

Evaluate the use case.

---

# 72. CURSOR

Cursor must be:

- validated
- stable
- opaque if internal details should not be exposed

---

# 73. CURSOR TAMPERING

If cursor contains user-controlled decoded parameters, verify validation.

---

# 74. SORTING

Whitelist sort fields.

Never insert raw `sort` directly into SQL.

---

# 75. SORT DIRECTION

Validate:

```text
asc
desc
```

---

# 76. FILTERS

Map supported filter semantics.

---

# 77. SEARCH

Verify:

- length bounds
- normalization
- DB cost
- user-visible semantics

---

# 78. DATE FILTER

Verify:

- inclusive/exclusive boundaries
- timezone
- invalid range

---

# 79. `from > to`

Business validation must reject or define behavior.

---

# 80. CACHING

REST endpoints can use:

- Cache-Control
- ETag
- Last-Modified
- CDN

Verify only where caching actually exists.

---

# 81. PRIVATE RESPONSE CACHE

Authenticated responses must not accidentally be shared-cached across users.

---

# 82. CACHE KEY

If response depends on:

- Authorization
- tenant
- locale

cache must respect that.

---

# 83. ETAG

If optimistic conditional updates exist:

verify `If-Match` semantics.

---

# 84. 304

For conditional GET verify response behavior.

---

# 85. IDEMPOTENCY

Classify endpoint:

```text
SAFE
IDEMPOTENT
NON-IDEMPOTENT
CONDITIONALLY IDEMPOTENT
```

---

# 86. POST RETRY

For critical POST:

```text
request commits
↓
response lost
↓
client retries
```

Analyze duplicate consequences.

---

# 87. PAYMENT / ORDER / BOOKING

These especially require idempotency analysis.

---

# 88. IDEMPOTENCY KEY STORAGE

If present:

verify:

- TTL
- user scope
- endpoint scope
- payload consistency
- persistence

---

# 89. SAME KEY DIFFERENT PAYLOAD

Must have defined response.

One key must never silently return the result of an entirely different operation.

---

# 90. IN-MEMORY IDEMPOTENCY

Not sufficient for multi-instance deployments or restarts if guarantees must be durable.

---

# 91. CONDITIONAL UPDATE

For concurrent edits verify:

- version
- ETag
- updatedAt
- DB atomicity

---

# 92. LOST UPDATE

Scenario:

```text
Client A reads version 1
Client B reads version 1
A updates
B updates
```

If B blindly overwrites A, verify whether that is acceptable.

---

# 93. PUT/PATCH RACE

HTTP method alone does not solve concurrency.

---

# 94. DELETE VS UPDATE RACE

Simulate:

```text
A delete
B update
```

Which final state is permitted?

---

# 95. CREATE DUPLICATE

Business unique constraints must prevent duplicates even if the client omits an idempotency key where domain requires uniqueness.

---

# 96. ERROR RETRYABILITY

For each error code ask:

```text
Should client retry?
```

---

# 97. VALIDATION ERROR

It makes no sense to automatically retry an identical payload.

---

# 98. RATE LIMIT

Retry can make sense after an appropriate cooldown period.

---

# 99. SERVER ERROR

Transient candidate, but not every 500 should be retried infinitely.

---

# 100. TIMEOUT

For write timeouts:

outcome can be unknown.

---

# 101. ASYNC API

If an endpoint starts long-running work:

verify pattern:

```text
POST /jobs
↓
202 + jobId
↓
GET /jobs/:id
```

or other documented pattern.

---

# 102. FAKE ASYNC

An endpoint returning 200 "success" immediately while work can subsequently fail permanently can mislead the client.

---

# 103. JOB STATUS

Verify:

- pending
- running
- success
- failed

---

# 104. POLLING

If client polls status:

verify rate and expiration.

---

# 105. CALLBACK / OUTBOUND WEBHOOK

If API subsequently notifies client via webhook:

verify reliability and idempotency.

---

# 106. LONG-RUNNING HTTP

If an endpoint keeps HTTP requests open for minutes:

verify proxy/server timeouts and resource costs.

---

# 107. FILE DOWNLOAD

Verify:

- authorization
- content type
- content disposition
- range requests where needed
- streaming

---

# 108. FILE NAME

User-controlled filename in Content-Disposition must be securely encoded and sanitized.

---

# 109. RANGE

For media or large downloads, Range support can be critical.

Do not require Range for small JSON/file endpoints without reason.

---

# 110. UPLOAD

For multipart:

verify:

- size limit
- file count
- field limits
- streaming
- cleanup

---

# 111. EMPTY FILE

Validation according to domain.

---

# 112. MULTIPLE FILES

Verify total size limit, not just per-file limit.

---

# 113. PARTIAL UPLOAD

If connection drops:

temporary file cleanup.

---

# 114. CONTENT TYPE

Client-provided header is not sufficient security proof.

---

# 115. URL INPUT

If API accepts URLs:

this can be an SSRF attack surface.

Full security audit later, but map trust boundary now.

---

# 116. CALLBACK URL

Same.

---

# 117. REDIRECT URL

Auth/payment redirect URLs must be whitelisted according to the business/security model.

---

# 118. HOST HEADER

If API builds absolute URLs from the Host header:

verify trusted proxy and host validation.

---

# 119. PROXY

Determine:

- forwarded proto
- forwarded host
- forwarded for
- trust proxy configuration

---

# 120. CLIENT IP

If rate limiting or auditing uses IP, verify that attacking clients cannot spoof trusted forwarding headers.

---

# 121. CORS

Map:

- allowed origins
- credentials
- methods
- headers

Remember:

CORS is not API authorization.

---

# 122. WILDCARD + CREDENTIALS

Check framework behavior.

---

# 123. PREFLIGHT

OPTIONS requests must not accidentally require the same auth as business requests if browser integration prevents it.

---

# 124. CSRF

If API uses cookies/sessions:

verify CSRF protection.

---

# 125. BEARER TOKEN

If credentials are not browser-ambient, CSRF threat model is different.

---

# 126. COOKIE ATTRIBUTES

If cookie auth exists:

- Secure
- HttpOnly
- SameSite

according to architecture.

---

# 127. CONTENT NEGOTIATION

If API claims to be JSON-only:

verify Content-Type handling.

---

# 128. INVALID JSON

Must yield controlled 4xx, not a generic crash or 500.

---

# 129. BODY SIZE

JSON body must have reasonable bounds per endpoint.

---

# 130. DECOMPRESSION

If server accepts compressed requests, check decompression bomb risk where relevant.

---

# 131. SERIALIZATION

Response serialization can fail due to:

- circular references
- unsupported types
- BigInt
- dates

depending on stack.

---

# 132. BIG INTEGER

JavaScript backends can suffer precision loss on large integer IDs from DB.

Verify actual stack.

---

# 133. DATE FORMAT

API must use a stable canonical representation.

Verify timezone and offset handling.

---

# 134. DECIMAL

Financial decimal values must not carelessly pass through binary floating point if precision has business significance.

---

# 135. NULL

Response schema must clearly distinguish:

- field absent
- field null

if clients depend on this difference.

---

# 136. BOOLEAN STRING

Look for inconsistencies:

```json
{"active": "true"}
```

vs:

```json
{"active": true}
```

---

# 137. OPENAPI

If OpenAPI exists:

compare spec against actual routes.

---

# 138. DOCUMENTED, NOT IMPLEMENTED

Endpoint or spec may promise fields or statuses that runtime code never returns.

---

# 139. IMPLEMENTED, NOT DOCUMENTED

Public API drift.

---

# 140. REQUIRED FIELD DRIFT

OpenAPI states required, code does not demand it or vice versa.

---

# 141. TYPE DRIFT

Spec integer, runtime string.

---

# 142. STATUS CODE DRIFT

Spec 404, runtime 200/null.

---

# 143. SECURITY SCHEME DRIFT

Spec claims auth required, route is public or vice versa.

---

# 144. CONTRACT TESTING

If API serves multiple clients:

contract testing can carry major value.

Do not demand enterprise tooling without need.

---

# 145. CLIENT GENERATION

If clients use generated SDKs from OpenAPI:

spec drift becomes significantly more severe.

---

# 146. BACKWARD COMPATIBILITY

For every change ask:

> Does the old client continue to function?

---

# 147. FIELD REMOVAL

Most common breaking response change.

---

# 148. TYPE CHANGE

Example:

```text
id: integer
```

becomes:

```text
id: string
```

can break clients.

---

# 149. ENUM

Unknown enum handling must be factored in.

---

# 150. ERROR CHANGE

Changing an error code can be breaking if clients implement specific UX flows around it.

---

# 151. PAGINATION CHANGE

Offset -> cursor may require versioning or a compatible transition phase.

---

# 152. DEFAULT SORT CHANGE

Can be user-visible breaking behavior even without schema alteration.

---

# 153. DEFAULT VALUE CHANGE

Same.

---

# 154. BOOLEAN DEFAULT

Omitted field can change semantics following a backend release.

---

# 155. FIELD SEMANTICS

The most dangerous breaking change preserves the data type but alters the meaning.

---

# 156. RATE LIMITING

Map:

- global
- user
- IP
- endpoint
- tenant

---

# 157. LIMIT RESPONSE

Verify status code and retry signaling.

---

# 158. LOGIN LIMIT

Authentication endpoints require abuse protection according to the threat model.

---

# 159. EXPENSIVE ENDPOINT

Search, export, and reports may require stricter capacity controls.

---

# 160. RATE LIMIT BYPASS

If rate limiting relies on spoofable headers:

problem.

---

# 161. DISTRIBUTED RATE LIMIT

In-memory limiting is not global across multiple instances.

It can still serve as useful local defense, but do not present it as a global guarantee.

---

# 162. CACHE + RATE LIMIT

Cache hits and misses can carry drastically different backend costs.

---

# 163. API TIMEOUTS

For each critical endpoint determine:

- server timeout
- reverse proxy timeout
- downstream timeout

---

# 164. CLIENT TIMEOUT SHORTER THAN SERVER

If client gives up after 10 s while backend continues 60 s expensive work, wasted processing accumulates.

---

# 165. SERVER TIMEOUT SHORTER THAN DOWNSTREAM

Illogical timeout budget.

---

# 166. CANCELLATION

If HTTP request disconnects:

does DB/network work continue?

Correct behavior depends on operation semantics.

---

# 167. MUTATION CANCELLATION

Do not cancel durable critical mutations blindly when a client disconnects.

---

# 168. READ CANCELLATION

Expensive reads can often be safely cancelled.

---

# 169. TRACEABILITY

For serious API errors it is valuable to have:

- request ID
- trace ID

If present, verify consistent logging and propagation.

---

# 170. REQUEST ID SPOOFING

If client supplies its own ID, server should validate or generate an internal ID so logs cannot be easily manipulated.

---

# 171. OBSERVABILITY

For each endpoint it should be possible to observe:

- latency
- errors
- status codes
- throughput

where production maturity warrants it.

---

# 172. HIGH CARDINALITY METRICS

Do not insert:

- user ID
- raw URL
- email

as metric labels without understanding cardinality and privacy impacts.

---

# 173. LOGGING

Do not log entire request/response bodies without sanitization.

---

# 174. AUTH HEADER

Never plain-text in logs.

---

# 175. COOKIE

Same.

---

# 176. PASSWORD

Same.

---

# 177. PAYMENT DATA

Same.

---

# 178. HEALTH ENDPOINT

If present:

verify it does not expose:

- secrets
- internal topology
- verbose stacks

---

# 179. DEBUG ENDPOINT

Look for:

```text
/debug
/test
/internal
/admin/dev
```

in production routes.

---

# 180. DOCUMENTATION ENDPOINT

Swagger UI in production is not automatically a vulnerability.

However, verify:

- sensitive internal APIs
- auth
- product policy

---

# 181. GraphQL / RPC ALONGSIDE REST

If backend provides multiple API paradigms:

verify that identical business rules are not implemented inconsistently.

---

# 182. LEGACY ENDPOINT

Older endpoints may carry weaker validation or auth logic.

---

# 183. DUPLICATE BUSINESS OPERATIONS

If there exists:

```text
POST /users/:id/activate
```

and:

```text
PATCH /users/:id { active: true }
```

verify that both enforce identical rules.

---

# 184. ADMIN BYPASS

Internal/admin APIs must not mutate DB directly if that bypasses critical invariants without clear intent.

---

# 185. BULK API

Bulk create/update/delete requires dedicated analysis.

---

# 186. BULK PARTIAL FAILURE

Define:

- all-or-nothing
- per-item result
- stop on first failure

---

# 187. BULK RESPONSE

Client must know which items succeeded.

---

# 188. BULK AUTHORIZATION

Each item must be authorized, not just the first one or parent collection.

---

# 189. BULK SIZE LIMIT

Do not permit unlimited item counts.

---

# 190. BULK TRANSACTION

Do not wrap massive batch operations in a single transaction without evaluating lock and time impacts.

---

# 191. EXPORT API

If generating large reports:

verify:

- sync vs async
- memory
- authorization
- expiration

---

# 192. IMPORT API

Verify:

- schema
- duplicate handling
- transaction
- partial failure
- idempotency

---

# 193. SOFT DELETE API

Verify how list and detail endpoints treat deleted resources.

---

# 194. RESTORE API

If a resource can be restored:

verify conflict resolution with newer resources occupying the same unique key.

---

# 195. ARCHIVE

Archive semantics should be distinguished from delete if product differentiates them.

---

# 196. STATE MACHINE ENDPOINTS

If resource has lifecycle:

```text
DRAFT
SUBMITTED
APPROVED
REJECTED
```

verify allowed transitions.

---

# 197. INVALID TRANSITION

Endpoint must not permit:

```text
REJECTED -> APPROVED
```

if domain disallows it.

---

# 198. CONCURRENT TRANSITION

Two requests can attempt divergent transitions from the same state.

Requires DB-level/atomic protection.

---

# 199. APPROVAL

Authorization may depend on current state.

---

# 200. STATE TRANSITION AUDIT LOG

High-value workflows may require audit trails.

---

# 201. IDEMPOTENT COMMAND

Repeated:

```text
POST /orders/:id/cancel
```

can legitimately return "already cancelled" without repeating side effects.

---

# 202. SIDE EFFECTS

Map whether API requests trigger:

- email
- notification
- event
- payment
- webhook
- file operations

---

# 203. RESPONSE BEFORE SIDE EFFECT

If API returns success prior to durable enqueueing of a critical side effect:

work can be lost.

---

# 204. RESPONSE AFTER NON-CRITICAL SIDE EFFECT

If request blocks waiting for email provider, it unnecessarily inflates latency and failure surface.

---

# 205. ATOMICITY

For each endpoint ask:

> What minimal part must be atomic for client success to remain truthful?

---

# 206. RETRY SAFETY

For each write endpoint ask:

> Can the exact same request safely arrive again?

---

# 207. PROXY RETRY

Not only clients.

Reverse proxies, gateways, or service meshes can sometimes retry requests.

Verify platform configuration before asserting.

---

# 208. MOBILE RETRY

Mobile clients may retry following a timeout even though the server operation actually succeeded.

---

# 209. DOUBLE CLICK

Frontend can dispatch two duplicate requests.

Backend must protect critical invariants without relying on disabled UI buttons.

---

# 210. CONTRACT MATRIX

For critical endpoints construct:

| Route | Input | Success | Errors | Idempotency | Compatibility risk |
|---|---|---|---|---|---|

---

# 211. AUTHORIZATION MATRIX

| Route | Principal | Resource ownership | Role/permission | Verified |
|---|---|---|---|---|

---

# 212. STATUS MATRIX

| Scenario | Expected HTTP | Actual | Consistent |
|---|---|---|---|

---

# 213. IDEMPOTENCY MATRIX

| Endpoint | Retry possible | Duplicate consequence | Protection | Risk |
|---|---|---|---|---|

---

# 214. PAGINATION MATRIX

| Endpoint | Method | Max size | Stable order | Cursor/offset | Risk |
|---|---|---|---|---|---|

---

# 215. VERSIONING MATRIX

| Contract | Old clients | New clients | Breaking risk | Status |
|---|---|---|---|---|

---

# 216. TESTS

Review:

- route tests
- integration tests
- auth tests
- validation tests
- OpenAPI tests
- concurrency tests

---

# 217. HAPPY PATH TEST IS NOT ENOUGH

Critical endpoints need failure coverage.

---

# 218. AUTH MATRIX TEST

For sensitive routes test:

```text
unauthenticated
wrong user
correct user
admin
```

where relevant.

---

# 219. VALIDATION TEST

Test boundaries:

- empty
- null
- max
- malformed
- unknown enum

---

# 220. IDEMPOTENCY TEST

Send the exact same request twice.

---

# 221. CONCURRENT TEST

Send conflicting requests in parallel.

---

# 222. PAGINATION TEST

Test duplicate sort values and data mutations across pages.

---

# 223. OPENAPI CONTRACT TEST

If spec exists, verify runtime responses conform to spec.

---

# 224. OLD CLIENT CONTRACT TEST

If fixtures or generated clients of older versions exist, utilize them.

---

# 225. FINDING FORMAT

Every serious finding must include:

```text
ID:
Severity:
Category:
Confidence:
Status:

Method:
Route:
Authentication:
Authorization:
Request schema:
Response schema:

File:
Handler:
Relevant code:

Problem:

Evidence:

HTTP Flow:

Request:
Server processing:
Response:

Reproduction:

Expected HTTP behavior:

Actual/Possible behavior:

Security impact:

Data impact:

Client compatibility impact:

Retry/idempotency impact:

Root cause:

Recommended remediation:

Regression/contract test:

Runtime verification:

Complexity:
XS / S / M / L / XL
```

---

# 226. SEVERITY

Use:

## P0 - CRITICAL

- cross-user/tenant private data access
- privilege escalation via API
- duplicate irreversible financial action
- exposed critical secret

## P1 - HIGH

- critical IDOR
- common retry creates duplicate business effect
- major contract flaw breaks primary client flow
- data corruption via concurrent API usage
- severe auth/authorization inconsistency

## P2 - MEDIUM

- significant API correctness problem
- inconsistent error/status behavior with real client impact
- pagination/versioning bug with serious consequences

## P3 - LOW

- limited contract edge case
- minor inconsistency

## P4 - IMPROVEMENT

- API design/maintainability/documentation improvement without confirmed functional failure

---

# 227. CONFIDENCE

Use:

```text
HIGH
MEDIUM
LOW
```

HIGH:

route + handler + data layer directly confirm scenario.

MEDIUM:

strong evidence, but production proxy/client behavior not verified.

LOW:

depends on external API gateway/client contract not accessible.

---

# 228. STATUS

Use:

```text
CONFIRMED
LIKELY
THEORETICAL
NOT VERIFIED
```

---

# 229. FALSE-POSITIVE PREVENTION

Before any P0/P1/P2 finding, verify:

1. route
2. middleware
3. request validator
4. auth
5. authorization
6. service
7. DB constraint
8. response serializer
9. API spec
10. tests

Do not conclude from route files alone simply because authorization is absent in the handler.

---

# 230. DO NOT ENFORCE "PURE REST"

An RPC-like command route can be superior to an unnatural PATCH model.

Example:

```text
POST /orders/:id/cancel
```

can be clearer than:

```text
PATCH /orders/:id
{"status":"cancelled"}
```

if cancellation has business rules and side effects.

---

# 231. DO NOT DEBATE ENDLESSLY ABOUT 400 VS 422

If the contract is consistent and clients operate properly:

this is secondary.

---

# 232. DO NOT INTRODUCE VERSIONING UNNECESSARILY

If API has only one tightly coupled client and no compatibility issues:

versioning can be P4.

---

# 233. DO NOT ADD RESPONSE ENVELOPE JUST FOR STYLE

```json
{"data": ...}
```

is not automatically better than direct resource representation.

---

# 234. DO NOT ADD HATEOAS AUTOMATICALLY

Do not require hyperlinks in every API response unless the product genuinely benefits.

---

# 235. DO NOT MODIFY CODE

During audit:

- do not change routes
- do not change status codes
- do not add versioning
- do not change schemas
- do not add idempotency keys
- do not change auth

Finish the audit first.

---

# 236. OUTPUT - REST_API_FORENSIC_AUDIT.md

Structure the final report:

## 1. Executive Summary

- API stack
- route count
- auth model
- contract quality
- highest risks
- production readiness

## 2. Route Inventory

## 3. HTTP Method / Resource Semantics

## 4. Request Validation Audit

## 5. Response Contract Audit

## 6. Error Contract Audit

## 7. Authentication Coverage

## 8. Authorization / IDOR Audit

## 9. Tenant Isolation Audit

## 10. Status Code Audit

## 11. Pagination Audit

## 12. Filter / Sort / Search Audit

## 13. Idempotency Audit

## 14. Concurrency / Lost Update Audit

## 15. Async Operations Audit

## 16. Upload / Download API Audit

## 17. Caching / Conditional Request Audit

## 18. CORS / CSRF / Proxy Context

## 19. API Versioning / Compatibility

## 20. OpenAPI / Documentation Drift

## 21. Observability

## 22. Testing Coverage

## 23. Findings Summary

| ID | Severity | Method/Route | Category | Problem | Confidence | Status |
|---|---|---|---|---|---|---|

## 24. P0 Findings

## 25. P1 Findings

## 26. P2 Findings

## 27. P3 Findings

## 28. P4 Improvements

## 29. Things Done Well

## 30. Unknown / Not Verified

## 31. Remediation Roadmap

---

# 237. SECOND PASS - UNAUTHENTICATED ATTACK

For each non-public route strip authentication.

Ask:

> Which middleware specifically rejects the request?

---

# 238. SECOND PASS - WRONG USER ATTACK

For each resource ID imagine:

```text
authenticated User B
↓
sends ID belonging to User A
```

Ask:

> Where is ownership checked?

---

# 239. SECOND PASS - FIELD TAMPERING

For each write request add unexpected fields:

```json
{
  "role": "admin",
  "ownerId": "other-user",
  "status": "paid"
}
```

Ask what the backend does.

---

# 240. SECOND PASS - DUPLICATE REQUEST

For each critical POST/PATCH:

```text
request A
request A again
```

concurrently and following a lost response.

---

# 241. SECOND PASS - CONCURRENT REQUEST

Execute:

```text
Request A
Request B
```

against the same resource.

Ask whether an update is lost or an invariant violated.

---

# 242. SECOND PASS - INVALID INPUT

For each parameter test:

- null
- empty
- oversized
- malformed
- unsupported enum
- wrong type

---

# 243. SECOND PASS - PAGINATION MUTATION

Scenario:

```text
client fetches page 1
↓
new record inserted
↓
client fetches page 2
```

Ask whether offset pagination can:

- skip
- duplicate

items.

---

# 244. SECOND PASS - OLD CLIENT

Retain older request/response expectations.

Apply current backend.

Search for breaking changes.

---

# 245. SECOND PASS - TIMEOUT RETRY

Critical write:

```text
request sent
↓
server succeeds
↓
response delayed/lost
↓
client timeout
↓
retry
```

Ask what gets duplicated.

---

# 246. SECOND PASS - PROXY

If backend is deployed behind proxy/gateway:

verify:

- host
- proto
- client IP
- timeout
- body size

---

# 247. SECOND PASS - BULK

If bulk endpoints exist:

simulate one invalid item in the middle of a batch.

Ask what remains committed.

---

# 248. SECOND PASS - ASYNC

For 202/job endpoints:

simulate:

```text
accepted
↓
job permanently fails
```

Ask how the client discovers the failure.

---

# 249. SECOND PASS - API SPEC

Compare each critical route against OpenAPI spec if present.

Search for silent drift.

---

# 250. SECOND PASS - ERROR CONTRACT

For each failure type ask:

> Can the client reliably distinguish what action to take?

For example:

- fix input
- login
- ask permission
- retry
- stop retrying
- show conflict

---

# 251. FINAL QUALITY GATE

Before final response verify:

- all critical routes are inventoried
- GET side effects are verified
- auth and authorization are not conflated
- IDOR is checked against real resource ownership
- nested route parent-child relations are verified
- mass assignment is analyzed
- response fields do not accidentally expose internal/sensitive data
- status code findings have real client impact
- error codes are analyzed as machine contracts
- pagination has stable ordering
- unbounded list endpoints have real growth context
- critical POST/PATCH have retry/idempotency analysis
- concurrency is not inferred from HTTP method alone
- timeout write scenarios include unknown outcome
- bulk endpoints have partial failure semantics
- 202 has a mechanism to trace final outcomes
- OpenAPI is compared against runtime code where present
- old client compatibility is analyzed where critical
- proxy/CORS/CSRF are not confused with authorization
- pure REST aesthetics are not prioritized over correctness
- P4 design improvements are clearly segregated from real bugs

---

# FINAL RULE

I do not want a report like:

> Use proper HTTP methods, status codes, pagination, and OpenAPI.

That is not a REST API audit.

I am looking for problems like:

```text
PATCH /users/:id
↓
authentication verifies caller
↓
handler loads user by :id
↓
no ownership/role check
↓
ordinary user can modify another account
```

or:

```text
POST /payments
↓
payment succeeds
↓
response lost
↓
client retries same POST
↓
server has no idempotency protection
↓
payment is charged twice
```

or:

```text
GET /reports/export
↓
endpoint creates export record
↓
browser prefetch/crawler hits URL
↓
server creates report without explicit user action
```

or:

```text
PATCH /profile
{
  "name": "Zoran",
  "role": "admin"
}
↓
request body passed directly into ORM update
↓
role changes because field was not whitelisted
```

or:

```text
GET /projects/A/tasks/B
↓
caller may access project A
↓
task B actually belongs to project C
↓
handler loads B only by task ID
↓
parent project scope is never verified
```

or:

```text
GET /items?page=1
↓
new item inserted at top
↓
GET /items?page=2
↓
offset shifted
↓
client receives duplicate item and misses another
```

or:

```text
POST /jobs
↓
server returns 200 "success"
↓
job runs asynchronously
↓
job permanently fails
↓
client has no job ID or failure channel
↓
user believes operation completed
```

These are the REST API problems you need to find.

Think through:

- HTTP semantics
- resource identity
- trust boundary
- authorization
- validation
- stable contracts
- retry
- idempotency
- concurrency
- pagination
- old clients
- proxy/runtime behavior

For each serious finding you must be able to answer:

> Which exact HTTP request triggers the problem?

> Which principal sends it?

> Which resource is affected?

> Which status/body does the client receive?

> What happens if the exact same request arrives twice?

> What happens if two clients mutate the same resource concurrently?

> Does the old client still understand the response?

If not provable:

**NOT VERIFIED.**

If it is merely REST style without real impact:

**P4 - IMPROVEMENT.**

It is better to find 6 real contract/auth/idempotency problems than to write 100 academic REST recommendations.

The goal is to produce a forensically precise REST API audit from which each serious finding can be directly converted into:

- reproduction request
- integration test
- authorization fix
- schema/contract correction
- idempotency protection
- concurrency regression test
- compatibility safeguard
- production API hardening plan

分类与标签

编程开发、REST接口审计、API安全、后端开发

前往 AI 图片创作