APIs Are For Life

APIs do lots of things. One of the most important things is that they make the work you've been doing available to others. It doesn't matter if your API is HTTP, gRPC, C++, Python, a string of characters, a bunch of 1's and 0's stored in some kind of persistent store, or something else entirely. Without an API it's unusable, locked away where no-one can get at it and you've wasted your time.

If your API is your user interface, then approach it like one. The best user interfaces don't just make it easy to do what you want, they make it easy to understand how you should be using them, and they make it hard to do the wrong thing. If you're using a metaphor for part of your API, use it for the whole thing. Ensure your objects, whatever they are, are consistently used and named. Your API is your contract, so you have to live up to it, but that goes both ways. If the user makes a mistake, you don't have to guess what they meant, just make it obvious what the mistake was.

And that's the easy part. The hard part is future-proofing your API. Once you've released your API and your customers start using it, they're going to expect you to continue to uphold the contract, so how can you change it? You can extend it. You can make it do new things and handle different cases. You can version it. You can (and should) support at least the previous version of your API. The worst thing you can do is make it subtly different, so that it appears to continue to do the same thing, but really it doesn't. You might think it's a bug fix, but does your customer? If they built an entire workflow assuming that the way it works is the right thing and you "fix" it they're going to be upset. But that's a story for another day.