doc: api: Clean up and reorganize a bit

Move the section describing the requirements for a new API out of the
peripheral API header, clarify the requirements for upgrading an API to
experimental and unstable clearly in the corresponding sections. Add a
link to the API stability page.

Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>