Versioning through HTTP Headers was the spark for why I was looking around for guidelines. I think it is the better way to go other than URL versioning.
Remember doing an integration with a finance company's API. I read their documentation,write the code,all works fine, we are moving towards go live date. A week later, my integration fails. I try hell knows how many things, eventually contact their lead dev asking what am doing wrong...The answer was "Oh,emm,yes,we've kind of changed the response format slightly, it's not in the documentation"... I got that fixed.. It's working again.Then, we suppose to go live next week.2 days before go live date I get told we are cancelling all business with the company...All the integration code goes into a bin.
"Services MUST increment their version number in response to any breaking API change. See the following section for a detailed discussion of what constitutes a breaking change. Services MAY increment their version number for nonbreaking changes as well, if desired.”
Of course you want to mention that a new field was added and what it is for, but why do you need a big notice? Your clients should just continue to work.
I'm guessing this is the same as "adding another column to a db schema should not break your app". So basically don't iterate over objects (or iterate and only use keys you recognize) and you are fine.
That does not seem at all weird to me. The client side of it is the same as "don't SELECT *".