Platforms

For most of my career I've been working on platforms, From Flight Simulation to 2/D3D geospatial visualization to infrastructure. One of the keys to building platforms (or for anything really) is customer value. A long time ago a marketing instructor told me that developers build features, but customers buy benefits. Those two are very closely related, but they're not the same thing. When you're building a platform they intersect at your API. It doesn't matter if it's possible to do everything your customer wants with the API, it has to be easier for them to use the API now, not in 6 months or after a climbing a steep learning curve. If your API doesn't provide value then your customer will figure out a way around it, build their own internal API, and leave you stuck supporting it. This is true at every layer, from the OS to the UI.

So how do you build APIs that not only provide value now, but are extensible so you can keep adding features without pissing off your customers. There are many language specific things you can do. From optional parameters with default values to versioned input/output structures that your API later decodes (as an aside, did you know that most Win32 APIs take, as an input structure, some base type then check the size of the structure to determine the version?) you can isolate your customers from your internal implementations/choices.

But those technical details, as important as they are, aren't really the answer. The key is to understand that users of your APIs are customers, and treat them that way. That means that (within reason) the customer is right. As William Gibson said, "the street finds its own uses for things". If they find a new use for your API figure out the problem they're solving and help them solve it.

Treat your API as a contract and honor it. Make it simple to understand and do what your users expect. Make it hard to misuse. Don't surprise them with side effects. Don't leave things in a half-baked state. Think of the "Verbs" your API supports. REST makes it obvious. CRUD is just a set of verbs.

Bottom line, make your customers want to use your API, not roll their own.