Should I include HTTP Status Codes in JSON Responses?

[Michael Dunn]

Some API duplicate the HTTP response code inside of the JSON response:

HTTP Status Code: 401

{"status" : "401", "message":"Authenticate","code": 20003, "more
info": "http://www.twilio.com/docs/errors/20003"}

While others (such as Box) do not:

HTTP Status Code: 200

{
    "total_count": 1,
    "entries": [
        {
            "type": "user",
            "id": "181216415",
            "name": "sean rose",
            "login": "sean+a...@box.com",
            "created_at": "2012-05-03T21:39:11-07:00",
            "modified_at": "2012-08-23T14:57:48-07:00",
            "language": "en",
            "space_amount": 5368709120,
            "space_used": 52947,
            "max_upload_size": 104857600,
            "status": "active",
            "job_title": "",
            "phone": "5555551374",
            "address": "10 Cloud Way Los Altos CA",
            "avatar_url": "https://api.box.com/api/avatar/large/181216415"
        }
    ]
}

I'd appreciate people's thoughts on why you would/wouldn't choose one of these practices.

Thanks,

Mike

[mca]

Duplicative. Having it in two places increases chances for discrepancy.

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/groups/opt_out.

[Jack Repenning]

On Nov 15, 2013, at 11:58 AM, Michael Dunn <mi...@eikonomega.com> wrote:

> I'd appreciate people's thoughts on why you would/wouldn't choose one of these practices.

For error reporting, I like the draft spec "Problem Details for HTTP APIs",

http://tools.ietf.org/html/draft-nottingham-http-problem-04

which includes an optional "httpStatus" member, which I would use.

For non-error cases, I would not use it.

My rationale for leaving it out of the successful cases is: successful returns are handled by code, and it's easier for code to get the actual status from the response, than to dig it out of some (necessarily non-standard) spot.

My rationale for including it in http-problem returns is: error returns are, most importantly, handled by humans (maintainers of the client code), often when they're desperately flailing to figure out why their app is suddenly spewing errors into the logs, or onto customer screens. Desperate people deserve all the help we can give them--especially since they, annoyingly often, turn out to be us!

--
Jack Repenning
Repenni...@gmail.com

[André Tavares]

IMHO it doesn't make sense:

1) It's redundant

2) If it regards the HTTP request, it should remain in its "lifecycle". Doesn't make much sense to include protocol-related information/data in the response object which, in case of an error, should contain additional information regarding what went wrong with the call.

[msskiran]

It is not needed as people above have suggested. But if your API was not RESTful in the first place and you had custom error codes, to have backward compatibility once you move your API to a more RESTful one, it might be helpful to older clients to use with minimal changes. But if client has to change, then they might as well look at HTTP header.

[Jørn Wildt]

I have heard of a relatively good reason for including the HTTP status code in the response: some client side environments/frameworks does not give the client application code access to the HTTP status and thus, in order to cater for as many clients as possible, it may make sense to include the HTTP status code in the payload.

I cannot remember which environment it was - perhaps browser javascript?

/Jørn

--

[Mike Dunn]

I would agree with that sentiment.  If there are frameworks in which the status code is not accessible it would make sense to include it in the payload.  Can anyone verify Jørn’s guess about browser javascript and/or other situations in which this may be the case?

Thanks

--
Mike Dunn
Sent with Airmail

You received this message because you are subscribed to a topic in the Google Groups "API Craft" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/api-craft/MhITjXlzwxY/unsubscribe.
To unsubscribe from this group and all its topics, send an email to api-craft+...@googlegroups.com.

[Jeff Schmidt]

For the project I'm working on, most API access is via JSONP. This entails using <script> tags as a way to circumvent the browser same-origin policy. This is essentially an HTTP GET, but without the benefit of receiving any status code, or any other headers for that matter. The returned entity is JSON wrapped in a JavaScript callback function (the P or padding), which gets invoked browser-side.  The jQuery library allows for a timeout to be set, and if the callback is not invoked within that time the client can know something is wrong, but not what.

So, for JSONP requests, the API returns status within the returned JSON itself. This is not an HTTP status code, but rather an API status code along with additional messaging a client may presented to a user, such as an invalid ID, permission issues etc. Or the client may take action not requiring user involvement etc. Something like an unhandled server-side error will still rely on the timeout mechanism, but it's good to avoid those. :)

We've not yet moved to support CORS, but that is on the horizon.

Cheers,

Jeff

[Mike Kelly]

fwiw, I've had similar experiences with access to response headers
when doing CORS with IE9 and IE8's XDR. We ended up having to stick
links in the body.

--
Mike

http://twitter.com/mikekelly85
http://github.com/mikekelly
http://linkedin.com/in/mikekelly123