Successful API call (no errors): Success = True or Error = false ?

[TechBoyJK]

Curious as to what you fellow devs would expect when doing an API call.

I have a basic API in progress, and all of my calls return error = false if successful. Basically it starts out ERROR = false and as it goes through code, does error checking. If the request was processed without errors, error will remain = false.

Seems redundant to add 'success = true' when if it's not true... error will be equal to something besides false.

 

[brandonb]

I am the opposite of you.

The reason is you can call a function in an if...statement, and if it's true, continue to process.

(pseudo code)

BeginTransaction();

if(ValidateDataIntegrity())
{
    UpdateDatabase();
    CommitTransaction();
}
else
{
  RollbackTransaction();
}

(not that it is the best example, but you can get the idea)

 

[Crusty]

Depends on the API I guess.

If this is a web based api then I don't really expect there to be a status field in the response at all. I would expect proper HTTP response codes, and if required details about what went wrong in the response body when an error code is present.

 

[Markbnj]

Depends on the API I guess.

If this is a web based api then I don't really expect there to be a status field in the response at all. I would expect proper HTTP response codes, and if required details about what went wrong in the response body when an error code is present.

This, for web APIs definitely. For libraries, assuming the presence of exception handling in the language, then what I would want is either a valid return value or an exception. A valid return value could be false, of course. If an API call is supposed to check whether a file exists then I don't expect it to throw an exception if the answer is no.

 

[Berliner]

I have a basic API in progress, and all of my calls return error = false if successful. Basically it starts out ERROR = false and as it goes through code, does error checking. If the request was processed without errors, error will remain = false.

Thats the C / ANSI way.

Stick with it.

 

[TechBoyJK]

Here's an example of something really similar.

I have a remote function setup that checks to make sure a datasource is available.

It's called checkDSN

If the DSN is available it returns

{"error":false}

If the DSN is not available it returns

{"error":true}

 

[DaveSimmons]

I'm used to many Windows API calls returning either 0 = success or an error code which could be any nonzero number.

int error = SomeApiCall ( stuff ) ;

if ( error )
{
// NoooooOOOOooooOOOOoooo !! </vader>
}

But since this is Windows, I'm equally used to many calls returning 0 for failure and TRUE for success.

Or a resource handle, hopefully with NULL meaning an error occurred.

In short, I often have to look it up because you never know what to expect.

 

[Spungo]

I have a basic API in progress, and all of my calls return error = false if successful. Basically it starts out ERROR = false and as it goes through code, does error checking. If the request was processed without errors, error will remain = false.

In my inexperienced opinion, do whatever makes sense. What is the function's name? If you were to say it in English (get Gerry on the line!), how would you state it? You hopefully wouldn't not say that its true condition of being false would be not false, correct?

I'm still working on my first application that actually does something useful. I don't really know where I'm going with this, but I have the main window start with this:

bool projectChanged = false;

Why this? Because it sounds correct. When is the last time someone said "your hair looks different. is it exactly the same as before?" Probably never. We ask if things changed, not if they stayed the same.

Then in a few places I have this:

documentChanged();

Why? Because it sounds right.


At the end, I have an event:

private void MainWindow_Closed {
   if (projectChanged == true) {
      askSaveChanges();
   } 
}

In English, what does that line say? If the project changed, ask to save changes. It could just as effectively written sort of liike this:

if (documentChanged()) {
   askSaveChanges();
}

Just speak it to understand it. Did the document change? If true, ask to save changes.

I think of a lot of writing would improve if people spoke what they were writing. Here's my favorite game critic reading hate mail exactly as it is written. Flaws jump out immediately when you try saying what was written.
https://www.youtube.com/watch?v=mv04aKBhZ9U

I have a remote function setup that checks to make sure a datasource is available.

It's called checkDSN

If the DSN is available it returns

{"error":false}

If the DSN is not available it returns

{"error":true}

IMO, checkDSN should be a positive confirmation. Did you check the DSN? Yes? Then let's keep going.
What's the alternative? "Yes I checked the DSN. It responded No." Huh? I'm always thinking in terms of "yes" meaning "do something".

 

[TechBoyJK]

One thing I want to point out, and I'm wondering if I should apply two different tactics for these two cases.

Most of these api calls will return a struct, in json format. Not a boolean value.

And I'm writing these to do fairly specific error reporting. In these cases, there's a default error value in all of them. These api calls will always have an error value which determines whether or not the call returned with errors.

"error":false
"error":true

There will also be specific errors returned as well.. such as the following in the case that there is an email being processed:

"emailInvalid":true/false
"emailEmpty":true/false

So if you make the api call, you know it's successful if it returns without errors
"error":false

And I don't see the point in adding "success":true in the struct since "error":false already says the same thing.


Now in the case that I have an api call returning a boolean, then I wouldn't even have an 'error' variable to set to false.. it would just be true/false. In these cases yes, it would make more sense for checkDNS to return 'true' if it's online.

{false}
not
{"error":false}

 

[purbeast0]

Here's an example of something really similar.

I have a remote function setup that checks to make sure a datasource is available.

It's called checkDSN

If the DSN is available it returns

{"error":false}

If the DSN is not available it returns

{"error":true}

personally, i think the function name "checkDSN" is a terrible function name if it is returning simply a true/false value.

imo, something with that name wouldn't return anything and would just do something, such as checking the DSN.

also, if you ARE going to go with that ambiguous name, i'd expect it to return true when it is available, and false if it wasn't available. the way you are returning it seems backwards, which again, makes the name that much worse.

based on what you say the function does and what you explained for it, i'd expect it to be named "isDSNError" or "DSNHasError" or "isDSNAvailable" or something of that nature.

if you want to go with that name, i'd name it "checkDSNForErrors" or something, so you at least know what it's checking for.

and to the general question, it just completely depends on the API.

 

[brianmanahan]

i would throw an exception if there is a problem, and not return any sort of status on success

 

[Cogman]

In java land, My apis usually look like this.

If the "error" is recoverable and something that is expected to happen (find x, what do you do if x isn't found?) then I will return null and mark the method as @Nullable to indicate to the developer using it that this thing is shooting out unknowns.

If it really is an error, like the parameters passed in don't make sense or the database is laying in a smoldering pile of ash, then I throw an exception. Exceptions, for me, are indicators that there was either a bug in the code or a bug in the machine and as such whatever was happening at this moment is probably wrong. I prefer runtime exceptions and not checked exceptions because I feel that if we have gotten to the point of throwing something, I don't want it simply handled by the caller, I want it to break out as high as possible to stop the whole execution path from continuing in potentially a bad state.

I rarely throw exceptions, but frequently return nulls. (I'm fine with Optional's as well, but I tend to just rely on the annotation).

What I never do is use exceptions for control. It should be very rare that someone is sniffing for the exception and when they get it they retry or do some other execution path IMO.

 

[TechBoyJK]

i would throw an exception if there is a problem, and not return any sort of status on success

That's my line of thinking; at least in regards to when a struct is returned. Every struct will have an 'error' var that is either true (has errors) or false (no errors). I don't think it necessary to add 2nd var 'success' when in order for it to be true, the error var must be false. So if a script needs to be written that includes code to check and see if the api call returned successfully, all that needs to be checked is the error var. If it's false, that means no errors. No errors means success.

Now with api calls that are not structs, but are simple booleans, I would make it be positive. isDSNActive? true=yes false=no

 

[BoberFett]

Given my work with the WinAPI, I expect a zero for success or a non-zero as a code if there's an error.

Edit: DaveSimmons covered it already. Never "expect" anything, refer to the documentation.