How to distinguish error and result?

[constantine-fry]

Posting request to accounts/Account_ID/categories without JSON body returns following result:

 {
     code = "MALFORMED_JSON_ERROR";
      details =     (
     );
     reason = "The HTTP message body couldn't be parsed as JSON.";
  }

Would be nice to put it in inside error parameter.

[igstan]

If you mean, create a special error code that complains about a missing JSON body, then that's a reasonable request. We'll take a look.

[constantine-fry]

Sorry, I think you misunderstand me.
I suggest to have error object. So one can easily understand that he has got an error:

{
error =
{
     code = "MALFORMED_JSON_ERROR";
      details =     (
     );
     reason = "The HTTP message body couldn't be parsed as JSON.";
  }
}

[constantine-fry]

I've changed the title to meet me actual issue. Ideally, would be nice to have two types of JSON response:resultand error. If everything is fine you put response in result parameter. If someone like me uses API incorrectly you put response in error parameter.

So client code will look like this:

if (JSON has result) {
    // create result
} else {
    // create error based on error parameter
}

[igstan]

@constantine-fry this kind of dispatching can be done based on the received HTTP status code:

if (statusCode >= 400) {
  // error case
} else {
  // success case
}

Would that work for you? If not, I'm curious why.

[constantine-fry]

@igstan I think JSON object type shouldn't depends on HTTP status code, because JSON and status code are on different level of abstraction. But technically it will work for me :)

[igstan]

@constantine-fry I see what you're saying, and we've tried to not hijack HTTP status codes with custom domain logic, but in this particular case I don't think we're hijacking the HTTP protocol with domain logic.

I'll give it some more thought now that you brought this up, so if you have any scenario in which this approach makes things harder or muddier, let me know. The rule of thumb that I use is that any HTTP client can be used with our API representation without altering the API semantics because we've somehow added additional meaning over existing HTTP concepts. That doesn't seem to be the case here, but I won't mind being proved otherwise.