Hacker News new | past | comments | ask | show | jobs | submit | BstBln's comments login

Also seems they never heard about versioning via content negotiation :)


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.


I think so too, but even in case one disagrees, they should have mentioned it. Otherwise you’d think they never had heard of it :)


„Some services MAY add fields to responses without changing versions numbers. Services that do so MUST make this clear in their documentation“

WTF


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.


Assuming you’re working with JSON, it’s very easy to ignore extra fields and no reason to deploy any fixes for that :)


Where did it say it was an extra field? It says format change which could make for problems for sure!

edit: ah you must be referring to the GP. But the anecdote just says format change.


Yes, I think BstBln was using a context aware parser to formulate his reply.


Indeed :)


I'm not sure if your scenario is the same? An addition of a new field in a JSON response generally shouldn't cause breakage.

Though doing it without bumping a version should be rare, especially without a big documentation notice.


"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.


Especially they are suggesting that if not mentioned in the docs, a non-breaking add of a field should result in a new api version...


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 *".


You should be validating inputs to your application anyway.


Consider applying for YC's Spring batch! Applications are open till Feb 11.

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: