How to Accept a PHP API for Delivery: Documentation, Idempotency, and Error Codes

API acceptance isn’t about whether it works at all, but whether repeated calls remain safe and errors are instantly diagnosable.

Insights:How to Accept a PHP API for Delivery: Documentation, Idempotency, and Error Codes

Four Acceptance Criteria

Criterion Description
Documentation Third parties can self-test without reading the code.
Idempotency Duplicate requests do not produce duplicate data.
Error codes Each type of failure is distinguishable.
Logs Every call is traceable.

How to Verify Documentation

  • Are all fields and their types listed?
  • Are required and optional fields clearly marked?
  • Are request and response examples provided?
  • Are the meanings of error codes explained?

The standard is: hand the documentation to someone else and they should be able to complete a successful call within 30 minutes.

How to Verify Idempotency

  • Send the same request twice in succession and observe whether duplicate data is created.
  • After a network timeout retry, does it generate two separate records?
  • Do payment, ordering, and inventory APIs use unique identifiers for deduplication?

Common practice: the client passes a unique request ID, and the server uses that ID to detect duplicates.

How to Verify Error Codes

  • Do parameter errors, insufficient permissions, resources not found, business conflicts, and system exceptions each have distinct error codes?
  • Are retryable and non-retryable cases differentiated?
  • Is the error message specific enough to aid troubleshooting without leaking internal implementation details?

How to Verify Logs

  • Does every call log the request ID, duration, and result status?
  • For failed calls, can you look up summaries of the input and output parameters?
  • Can logs be correlated by request ID?

Acceptance Checklist

  1. Documentation covers all fields completely and examples can run out of the box.
  2. Repeated calls do not create duplicate data.
  3. Error codes are clearly categorized with explanatory descriptions.
  • Logs can trace the full lifecycle of a single call.
  • Timeouts and rate limiting have clear return values.
  • Sensitive information does not appear in plaintext within logs.
  • Common Substandard Behaviors

    • All errors return the same "Operation Failed" message.
    • Documentation only has field names, no examples.
    • Retries cause duplicate orders.
    • Logs are written only on success.

    Boundaries

    Acceptance criteria are organized according to conventional HTTP APIs. For third-party integrations or financial business scenarios, security and reconciliation requirements should be supplemented based on relevant standards.

    Related Reading: