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
- Documentation covers all fields completely and examples can run out of the box.
- Repeated calls do not create duplicate data.
- Error codes are clearly categorized with explanatory descriptions.
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: