5 ms·

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

• cosmodisk 7y ago
  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.
  • BstBln 7y ago
    Assuming you’re working with JSON, it’s very easy to ignore extra fields and no reason to deploy any fixes for that :)
    • gt2 7y ago
      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.
      • jsight 7y ago
        Yes, I think BstBln was using a context aware parser to formulate his reply.
        • BstBln 7y ago
          Indeed :)
  • BstBln 7y ago
    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...
  • jsight 7y ago
    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.
    • BstBln 7y ago
      "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.
• SahAssar 7y ago
  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 *".
• choward 7y ago
  You should be validating inputs to your application anyway.