Properly document what constitutes part of the public API and what doesn't

I didn't realize it until now, but apparently Drupal now properly defines what constitutes an API and what doesn't. Apparently we should use @api and @internal to specify this in contrib modules, unless we want to use the default definitions (but even then being explicit will do no harm, I guess).

For everything considered part of the public API, needless to say, backwards-compatibility should as much as possible be maintained.

So, I guess, we should discuss what we want as part of the API and what not, and then walk through the code and tag accordingly (and/or add proper documentation for this). (I actually have already used @internal twice, without knowing Drupal even used that. So a small start is made, for DatabaseCompatibilityHandlerInterface and FieldInterface::setFieldIdentifier(), which really shouldn't be used by contrib modules.)

Some thoughts:

• Plugin implementations, I think, should in general never be considered an API. However, in the case of the Views integration this becomes a bit blurry, as other modules might very well want to build on the Search API-provided plugins. They shouldn't be required to implement all that logic on their own (though our filter/argument handlers are now a lot smaller than in D7, fortunately). Can they maybe at least rely on the traits? Or on what else?
• Do we want to make all interfaces part of the API (the two current exceptions mentioned above), or which don't make sense? Do we really guarantee the interfaces for services stay the same? Or might we add more methods and only support overriding by extending the default class? (Is that even "allowed" to say?)
• What else is there were we want to stray from the norm, or be extra-clear?
• What I planned in any case: beginning with the stable release, we should definitely start using change records to notify people when we even potentially break backwards-compatibility. But, of course, just having a CR doesn't mean we can just change whatever.

Quick side reading: Wim Leers' presentation about this