API Heuristic Checklist – Common Falsehoods

I found yet another wonderful resource by Falsehoods. It’s on GitHub. kdeldycke/awesome-falsehood: 😱 Falsehoods Programmers Believe in (github.com)

Pro Tip: The webpage will save the status of the checklist until you reset the page cache or a timeout happens (180 days). So, you can use this as a workbook too.

API Checklist

Does the API assume that developer knows something about app?

Jargons on API vs UI Layer? Are they same vs different?

Does API documentation has list of App Jargons Used? Abbreviations?

Is the documentation of old versions preserved?

Are you forcing users to upgrade? What if they don't want to?

Does the document Differentiate Similar Sounding Terms? (Ex: Tags vs Topics vs Terms)

What if 200 Response Code with Error in Response Message? Silent Crash Scenario?

Rate Limit? Is it documented? Is there a code for it?

Is OAuth Lib reliable? What if it doesn't work someday? Service agreements?

Breaking Changes only in Explicit (or Major) Versions?

No feature disappears? or deleted without going in deprecated mode?

Backwards incompatible changes announced long before they are deployed.

We don't just update the docs and pretend the old spec (features) never existed. Facility for archive.

If there is an announcement of breaking changes, it will explicitly call out the changes. changed. It won't just be a dump of the entire new documentation.

Acknowledging customer if the bug is going to be fixed.

You are not removing features because someone raised bugs on it without acknowledging it.

A channel to report bugs made clear to customers. Github? Forms? Email?

Happy Testing!