How to handle API responds with DTO or Error Message

Question

I have a mobile app and an API. The mobile app is set up to expect back a DTO from the API but has no information if an request was unsuccessful. This needs to be updated so that better messaging is displayed to the user. I need to update the API and Mobile App so that I can send back a DTO on a successful request or a message that contains more detail than a generic error message.

I have started changing the API return types to IHttpActionResult so I can pass the HTTP status code AND data.

My first thought is to create a request wrapper which will have an error message and a generic data object.

public class ResponseWrapper
{
    public bool IsSuccess{get; set;}
    public string ErrorMsg {get; set;}
    public Object Data {get; set;}
}

I can then check the IsSuccess flag and proceed accordingly.

I also thought about implimenting error codes or using custom HTTP status codes. But I feel this adds complexity with maintaining codes and associated messages. With this preceived added complexity, this does not seem like the best solution.

Is there a better solution or one that is the standard practice for capturing a DTO or error message in the same api response?

Answer 1

From what I understand you are using a HTTP API for the communication between the client and the server.

I can only advise you from my personal preference, from my conventions. I am used to take advantage of the HTTP vocabulary.

For UI server APIs I only take advantage of status codes. I keep things simple. For all successful requests I send back status code 200. The requests that change state on the server do not send anything back to the client. In some cases data is requred and I bend from this convention and still send, but very rarely. For requests that don't change state like GET I just send a json back with status code 200. Now for any requests that fail (because of the user or something else) I don't add any data to it, the status code is enough. Status code 400 = generic invalid action from the user (invalid input). Status code 404 for GET requests when data is not found. Status code 500 for generic server error. Status code 401 when a request is made that requires authentication.

As you can see there aren't many codes to keep track of. You just need to follow some simple conventions. My basic conventions : try to not return any data when the requests are changing state (POST). Use only those 5 status codes.

Now, with my developer APIs, those that are ment to be consumed programtically by third parties (not the client APP UI), sometimes I also tend to add custom message near the HTTP status code and there I sometimes user more status codes to make the devs life easier, because they tend to need more information from a HTTP response.

Now why for the UI things can be kept simple? Because you can do most validation on the UI / client side. No need to return error information to the client, validate a request before it's sent. The UI client generally just needs to know if it failed or not, no other details (except if it's the user's fault or the server's fault).