Preferred method signature for API method involving DB interactions

Question

I recently got into discussion about how the method signature should look like for an API method which doesn't expose internal objects used by application to caller. Here is how situation looks:

1. Our API should expose one method say,

   public int updateSummary(String summaryMessage) {
   
         update_in_DB(summaryMessage);
         if (success) return 1;
         return -1;    }
   

or,

    public void updateSummary(String summaryMessage) {

          update_in_DB(summaryMessage);
         }

This method can be called by clients to update summary of operations.

2. The debate was, what should be Return_Type?

   i. void or,

   ii. something like int or, enum which conveys information around whether that operation was successful or not.

   iii. Return_Type can't be of type object/entity which represents actual object because it will expose internals of application to caller.

my point is, adding a return type like int/enum will make method testable (via unit testing) also, it enables caller to take action if this operation fails. But counter part to this was given that, it should be void and if operation fails error should get propagated to user because application should throw error indicating that something is wrong in deployment. Is anyone aware of any best practices or standards around this?

Answer 1

Exceptions can happen even in good code (e.g.: Oh no, server X has gone down and is not responding to attempts to save to DB), so I agree exceptions should always be propagated back.

That doesn't answer the return type question though. Is there a scenario whereby the database layer code might decide to NOT save (is validation happening here?) should a meaningful return type be returned? Examples might include a lack of authority to update that object, or a bad bit of data? If it is a simple Saved OK vs Exception then void is quite acceptable as a return type. If some sort of failure reason code response is required then a non-void response would be appropriate, a response code enumeration perhaps.

It isn't clear how "pure" your design is and if Update_in_DB is accepting data already validated and checked for authorisation as a pure DB action or if further checks will happen in this call.

Answer 2

IMHO, there are two different concepts here. One is if there’s anything meaningful you should return on your method in case the update succeeds, and that depends on the rest of the flow.

The other is how you should handle an exception thrown in the update process. There the good practice is usually catch the exception and raise another, more meaningful exception to let the client deal with.

For example, one client might have to abort if a bad update happens, other might retry, an third might ignore it...

That’s how I usually handle it, anyway, hope it’s helpful!