2

I am working on an implementation for an existing public API. Now I needed to change the implementation to throw an exception for a failure condition about which previously the API consumer was not informed in any way.

So basically I added a new possible exception.

Is the addition of this exception an incompatible change, a compatible change, or even not a change to the public API at all?

I am asking this, because my API is versioned according to Semantic Versioning 2.0.0, and depending on this, I need to decide if I need to bump the major, minor, or the patch version component for this change.

EDIT

Here is some more background information: The API is used to allow a consumer to retrieve files from a shared file system. Upon retrieval the file is moved from an incoming directory into an archive. Previously, when the move failed, the API did not make this clear in any way. Now, this API is supposed to throw an exception in case the archival move operation failed. If the file stays in the incoming directory, the consequences can be severe, because the same file might be treated as new again and again until manual intervention.

The API is provided as an object to be interacted-with by Ruby programs.

aef
  • 321
  • 1
  • 7
  • What problems can the failure cause in the current version? There's a big difference between replacing a seg fault with an exception throw, and rejecting technically-invalid-but-previously-working arguments with an exception. – Ixrec May 20 '16 at 09:33
  • I've updated my question to give more background on the purpose of the API and the potential problem. – aef May 20 '16 at 09:40

1 Answers1

2

Looks like a potentially large change. It depends on the language/platform, but if you're using Java and you've added a checked exception, then your clients may not even be able to compile their code against your library without changes. Regardless of compilation issues, your library has a potential change in behaviour affecting the using code, and your clients should be aware of that.

Brian Agnew
  • 4,676
  • 24
  • 19
  • I've updated my question about this: The API is a Ruby object. So there are only run-time consequences of this change. – aef May 20 '16 at 09:44
  • 2
    @aef: If your clients need to update their code to deal with the new exception, then it is a major, backwards-incompatible, change. – Bart van Ingen Schenau May 20 '16 at 10:55
  • So suppose I don't know exactly what my clients need to do. I know that the error wasn't communicated properly previously, but maybe it's fine for my client to let that exception bubble to the top and kill the process trying to use the API. I would say it would make sense to catch it, but it is not absolutely necessary. Or what would you say? – aef May 20 '16 at 15:31
  • I would say it's up to your clients. Only they can judge the impact this could have on their application – Brian Agnew May 20 '16 at 15:49