7

I'm writing a basic web API in Java that does what almost all others do: take input, validate it, then do CRUD operations on the DB. I've written several APIs before, and I've pretty much already figured out what constitutes a good response back to the client.

However, like most APIs, there are several layers of objects invoked between the front-door client API object and the code that actually executes queries against the database. I've always struggled to know what those database interaction objects should return back to the functions calling them.

I imagine that on errors I'll be throwing exceptions and catching them farther up the call stack. However, what do I return on successes? Here's what I've used before:

  1. Create - Return a boolean telling whether the create was successful or not
  2. Read - Return the object requested
  3. Update - Return a boolean telling whether the update was successful or not
  4. Delete - Return a boolean telling whether the delete was successful or not

I feel comfortable with the Read and Delete returns, because I can't think of what else you'd return in those situations. However, I have no idea what the best practice would be for return values from create and update functions. Should I return a new object with the updated values? Should I modify the object that was passed in? Should I just return a boolean value denoting success or failure?

Improve this question
2
  • If you are throwing exceptions, what purpose to the return values provide (other than, of course, the object returned from the read operation)? A create method that completes successfully should create the object. A create method that fails should throw an exception. I'm hard-pressed to imagine a case where you would want the method to complete successfully without successfully creating the object and to rely on the client to check the return method and figure out that something went wrong.
    – Justin Cave
    Jan 6, 2014 at 20:36
  • What kind/style you want to use with your API? Do you want to use HTTP metadata like in REST or do you want to return everything (errors, status, data.) as object?
    – imel96
    Jan 6, 2014 at 23:06

1 Answer 1

Reset to default
6

On create, I usually return the ID of the entity I just created. On an update, I return the object I just updated. Delete I usually don't return anything.

In the case of create, the most interesting part is the id of what was created. You throw an error if you couldn't create, so the boolean value you use isn't that interesting. You could also return the entire object with the ID.

On an update, returning the object with any modified fields (either by the updater or someone else) makes the most sense.

Delete either works or you throw an exception, no need for a return value.

Improve this answer
2
  • Most web interfaces will return some sort of status value, even if that value is an error code/message indicating that an exception was thrown (since you normally don't propagate exceptions over the wire). REST interfaces will always return some sort of status code.
    – Robert Harvey
    Jan 6, 2014 at 22:19
  • 1
    You're right, however the op mentions API's and functions, not REST, or web type API's.
    – Jim Barrows
    Jan 6, 2014 at 22:34

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.