API Responses

HTML & CSS
1

Hi

I have spent the past few days doing some research on the API responses of various online services. I am confused and I want your suggestions.

Do you think the following response makes sense and is industry standard way of generating an API response?

Success XML


<?xml version='1.0' encoding='UTF-8'?>
<output>
 <result>1</result>
 <message>User Added Successfully</message>
</output>

Success JSON


{"result":true,"message":"User Added Successfully"}

Error XML


<?xml version='1.0' encoding='UTF-8'?>
<output>
 <result>0</result>
 <message>User Already Exits</message>
</output>

Error JSON


{"result": false, "message":"User Already Exits"}

In the above responses, I am sending a “result” key that holds a boolean value (true / false). True in case of success and false in case an error occurs.

The second key is “message” that holds the respective messages.

The reason I am asking this question is because one of my friend claims that its not a standard way of sending API responses and that we do not need to send the “result” key at all. We should return a key “errMsg” with the error message in case of error and in case of success we can send a true value. And users who are using the API can check if the “errMsg” key exists then handle the response as an error otherwise assume it as a success.

So can someone throw some light on this please?

Thanks in advance

2

As a consumer of services, I prefer the ‘status’ or ‘result code’ always present as part of the response payload… less code for me to write.

Technically it doesn’t matter as long as you agree / document your format.

Why are you using 0/1 for xml, but booleans for JSON? keep it consistent.

3

For XML I am actually passing booleans, but it gets converted to 0 / 1. Not sure why

4

I don’t think there is a standard, but lots of people need to pass back a success flag and a message. From a consumer’s standpoint being able to check a boolean value is probably slightly more convenient than checking the message. Furthermore, you might want to transfer some information with success so presence of a message isn’t necessarily an indication of failure.

5

Industry standard or not being able to treat the response in a uniform way makes the life of the consumer easier. When crafting API responses I often include a status key and which usually matches up with the HTTP status of the response. For instance if there is a validation error I will return a HTTP status of 409 and in the response include the status like {status: 409, errors: }. If the request was a success something like {status: 200, message: “”}.

6

If you are going to do that why not just pass the responses as HTTP status codes? That is an industry standard.

7

Please re-read my post. The answer to your question is in there.

8

Yup, somehow read past that one.

I’ve used the http status code as error type indicator here and there, haven’t really fallen in or out of love with it. This was mainly for SOAPy stuff where one couldn’t send status messages effectively though.