What are most important first things in API design?

And how did your thoughts about API design evolve with time? What have you failed?

Especially if API is internal and full-stack / one-man; but you have to maintain for years.

Comments

[Yufan Lou]

but you have to maintain for years

WARNING: ranting without experience

I'd say the important thing for long term maintainability is a good mental model about how it works and a good test suite to go along with it to prevent regression.

For helping building that mental model I recommend Alloy. It can give you example graphs of your system for you to observe and discover both properties you want and those you do not want.

The test suites can start with integration tests and unit tests. With Alloy though you can usually find several nice properties to form a property test suite as well. (Hypothesis for Python) For security you can add a fuzz test at user inputs, but maybe that's not much of a concern for internal.

[Pacharapol Withayasakpunt]

For security you can add a fuzz test at user inputs, but maybe that's not much of a concern for internal.

When I say security, I actually mean website pentesting. Also, I do realize that all frontend code can be tampered to no end.

Although, it is true that the UI I created might be broken, by innocent users.

[Andrew Baisden]

I think it's important to have good documentation to go alongside it so that another developer who might not be familiar with the codebase can pick it up quickly.