Should an insert method return an object or throw exceptions

Question

I'm designing an API (first time) and it'll be a very public one (for a free online service).

I'm considering between returning structures such as InsertResult which can have the properties for when it fails or succeed (ie how much rows), the error messages and so on. Now, the other way is to just throw exceptions from the API insert method. I know this is kind of a "general and open" question but, what is considered more clean and polished for an API?

Scenario

The API is a DLL (which internally calls and consume Web Services from 4 or 5 different sources and that depending on things like geolocation decides which service to interact with). It's built using C# and Mono. Usage scenarios includes the API as library from desktop, mobile and web clients. That's indeed the problem, suppose an offline use case, from the web client it simply won't happen but from the mobile or desktop it can (from the mobile more frequently) what to do then? how to manage say an Insert call to store a mock from a mobile app just when it got offline. Or when another (server related) error happens.

Answer 1

Generally, you should throw an exception if the user tried to do something that is invalid. However, you should also provide a code path that allows the user to reasonably check for conditions which could throw an exception before they occur. If it's important (possibly for performance reasons) you might want to include a TryInsert method which safely handles invalid inserts and simply returns a bool valid to indicate success.

This applies to pure C# API's as well as service API's.

Answer 2

Throwing exceptions is the more natural way of handling errors and unexpected situations in C#/.NET. In addition, .NET provides you with the possibility to define your own exceptions or use one of the already existing ones.
Additionally by providing things like finally{} -blocks you can create really smooth goings when something goes wrong.
Checking return values is error-prone and it might make the process unstable, if the user does not react to your return-values properly. An unhandled exception usually stops the process and so Forces the user to check on the Background. That's my opinion, though.

On MSDN they say, that it is quite a reason to throw an exception, if for example a Parameter is wrong and you cannot continue with wrong Input.

Answer 3

As the question is "general and open" i think if we consider most used webservices like google,amazon i think they all follow the principle of giving details as precise as possible so anyone who is consuming it know what they are doing wrong.

If you just trow the exception it might be users of your API will bug you more.

So just to summarize its always a Good idea to define well known error codes and pass the same information to the client/consumer so they can easily figure out what is wrong with the call or what should i do to correct it. just for an example for some reason your api only accept specific encoding then user will be frustrated with that.

Answer 4

I recommend returning a detailed error. Since you are using a web service for consumption, not everyone will be using the same technology to interact with it. If you where making a framework, then I would say use exceptions as the developers would be using the same technologies to consume it. This is where exceptions are more useful, at a framework level.

UPDATED (The API in question is actually a framework): Since you are now talking about using a framework, you should throw exceptions as the clients have to reference the DLL and will have knowledge of the possible framework exception. To use the libraries it would have to be a CLR-compliant language so they should have the same concepts, classes, exceptions, etc...

Answer 5

For API, exception is always better. The API consumer can act upon various exceptions using catch blocks. If you use error message and error codes, you are asking your API consumer to write If statements. the snippet below is always cleaner than something where you have If condition to check error.

Hence from API consumer point of view its always cleaner that API throws exception

try
{
    yourAPIClass.YourMethod();
}
catch(YourException1 ex)
{
   action1();

}
catch(YourException2 ex)
{
   action1();

}

Here's a good guideline for writing and throwing exceptions http://blogs.msdn.com/b/kcwalina/archive/2005/03/16/396787.aspx