Why API Documentation Matters: 5 Common Mistakes and How to Fix Them

Crime 1: No Documentation

New front‑end developers often struggle when an API lacks any documentation, leading to confusion and wasted time.

Why documentation is needed?

It provides clear guidance for current and future developers.

Even simple interfaces generate more work through oral transmission than a written spec.

Memory fades; written docs preserve intent and usage.

How to write documentation?

Online documentation (e.g., Swagger) that is easy to update and share.

Local documentation (e.g., Word files) for offline reference.

Crime 2: Incomplete Documentation

Even when docs exist, they often omit crucial details such as parameter ranges, request methods, and especially the full set of possible response statuses.

Typical response structure

{
  s: 0/1, // status: 0 = success, 1 = failure
  m: 'xxxx', // message for failures
  r: [], // result data
  count: x // number of items
}

This structure fails to convey why a failure occurred because the single status code (s) is insufficient.

Improved response structure

{
  s: 0/1/2/3, // 0 = success, 1 = invalid parameters, 2 = user not found, 3 = no permission, etc.
  m: 'xxxx', // message for failures
  r: [], // result data
  count: x // number of items
}

Including all possible status codes lets front‑end developers handle each case appropriately.

Crime 3: Missing Parameter Validation

Back‑end services must validate incoming parameters to ensure data integrity and provide a first line of defense, even if the front‑end also performs validation.

Crime 4: Lack of Atomicity

APIs should be atomic: either all operations succeed or none do. Without atomicity, partial updates can leave the system in an inconsistent state.

Atomicity means a transaction is fully committed or fully rolled back, preserving data consistency.

Crime 5: Ongoing Interface Problems

To reduce recurring issues, back‑end developers should verify the following before releasing an API:

All parameters are validated.

All scenarios are tested, preferably with unit tests.

Responses are clear, accurate, and use appropriate HTTP status codes.

Documentation is complete and up‑to‑date.

Conclusion

Back‑end engineers should empathize with front‑end developers, check their own work first, and provide well‑documented, validated, atomic, and clearly defined APIs to foster smoother collaboration.