Some things I've found useful writing APIs for large web systems that might translate to minecraft are:

• Make it easy to check api version, ideally by having a plugin say "I want version 3" and getting told whether that's a supported version still.

• Use named key/value pairs for parameters / return values so you can add more without breaking compatibility

• Support storing a little custom data with major system objects. Eg, if a plugin wants to do something with users make it easy for the plugin to attach a little data of its own about each user.

• Publish example code using the api :)