Backend API Idioms - sgml/signature GitHub Wiki

Checklists

Check the following:

Make sure the HTTP status code returned is explicitly for the response (do not return 200 with an error message in the payload; do not skip a body response for a DELETE request)

Error messages returned with error status codes are generic

Only return stack traces in local or based on an environment variable

Make sure HTTP Security Headers are present (strict-transport-security, nosniff)

Make sure the acceptable token (access vs refresh) for an endpoint is specified

False Negatives

(strategy
  :name "false-404-mitigation"
  :domain "devsecops"
  :goal "Ensure integrity, observability, and resilience when closed-source APIs return misleading 404 responses"
  :risk "False negatives may cause data loss perception, UI failure, and security blind spots"
  :controls (
    ;; Resilience: Heuristic handling of anomalous 404s
    (tactic
      :name "heuristic-response-handling"
      :trigger (and (= request.method POST) (= response.status 404))
      :action (verify-resource-existence payload.id)
      :fallback (if resource-found (handle-success) (handle-error))
      :category "resilience")

    ;; Integrity: Post-operation verification to confirm backend state
    (tactic
      :name "read-after-write-verification"
      :trigger (= response.status 404)
      :action (query-resource payload.id)
      :decision (if resource-exists (treat-as-success) (raise-error "404 confirmed"))
      :category "data-integrity")

    ;; Robustness: Normalize client-side interpretation of known anomalies
    (tactic
      :name "status-remapping-layer"
      :scope "client-adapter"
      :rules ((= endpoint "/submit") (= response.status 404))
      :transform (set response.status 200)
      :note "Assume success with fallback"
      :category "robustness")

    ;; UX Continuity: Graceful degradation in UI layer
    (tactic
      :name "resilient-ui-fallback"
      :trigger (= response.status 404)
      :ui-actions (show-warning "Unexpected error. Data may be saved.")
                  (offer-retry)
                  (log-anomaly)
      :category "user-experience")

    ;; Observability: Log and trace anomalies for audit and escalation
    (tactic
      :name "anomaly-telemetry"
      :trigger (= response.status 404)
      :log-fields (:endpoint :payload :timestamp)
      :action (send-to-observability-pipeline "false-404-detected")
      :category "monitoring-and-traceability")
  )
  :compliance-tags (:resilience :observability :data-integrity :secure-client :audit-ready)
  :owner "devsecops-team"
  :status "active")

(tactic
  :name "auth-expiry-race-mitigation"
  :trigger (and (= response.status 404) (= request.auth-token.expired true))
  :action (remap-response-status 401)
  :fallback (trigger-token-refresh)
  :note "Ensure response status reflects auth state, not resource state"
)

References

https://www.searchapi.io/docs/amazon-search

https://www.cockroachlabs.com/docs/stable/start-a-local-cluster.html