I'm from 3scale - so factor in any bias filters!) - we definitely think of it as a contract between the provider and user of the API - could be very lightweight or heavyweight - but basically it's a bunch of rights on the API v's a promise of good behavior.
Actually a lot of the APIs that use us are B2B because you often have different tiers of access rights and limits + want to have approval steps etc. for sign-ups. These are pain to code yourself.
The change part is a big deal - we normally deal with it in two ways: 1) launching parallel services for major versions so people consciously migrate their apps, 2) incremental updates - docs are versioned but all the same calls work on the same endpoint. How the version is flagged in the call is rather independent (URL, header, type).
We also use the swagger docs framework (http://swagger.wordnik.com) to create interactive docs to try keep questions on the API itself to a minimum (people can play with it themselves).
Actually a lot of the APIs that use us are B2B because you often have different tiers of access rights and limits + want to have approval steps etc. for sign-ups. These are pain to code yourself.
The change part is a big deal - we normally deal with it in two ways: 1) launching parallel services for major versions so people consciously migrate their apps, 2) incremental updates - docs are versioned but all the same calls work on the same endpoint. How the version is flagged in the call is rather independent (URL, header, type).
We also use the swagger docs framework (http://swagger.wordnik.com) to create interactive docs to try keep questions on the API itself to a minimum (people can play with it themselves).