JSend: a specification for how JSON responses should be formatted

http://labs.omniti.com/labs/jsend

by wlue • 15 years ago

44 29 15 years ago

labs.omniti.com

The case for not using HTTP status codes (and thus breaking the cacheability and layering which are key to the REST model) is very weak. I just don't see why it all has to be wrapped in so many layers. GET /posts.json should return a list, GET /posts/1.json should return an object, and DELETE /post/1.json should result in a HTTP 204 if successful. In the case of errors, the response's status code and an object with exception information should suffice.

cgranade• 15 years ago

If I understood correctly, the JSend statuses should be used in conjunction with HTTP status codes when appropriate. I guess to me the spec seems redundant, as I don't see the advantage over using just HTTP status codes.

jrockway• 15 years ago

I agree, I am absolutely not a fan of this. REST is about documents; documents do not contain status information about the transport protocol used to transfer them, they just contain the free-form data that the application wants to convey to you.

For example, imagine the document at /foo/bar has moved to /new-api/foo/bar. Well, if you use HTTP for status, the server sends a 302 redirect when you try to request /foo/bar, and the user agent automatically grabs /new-api/foo/bar. If we reinvent this wheel for some reason, you can't use HTTP clients anymore, you have to use some proprietary bullshit client instead.

No thanks. This is not a problem and it does not need a "solution".

(I also agree about 204 responses for DELETE requests. The thing is gone, why does any data need to be sent back other than, "yeah, it went away"?)

tybris3• 15 years ago

The document is now in the data field of the returned JSON. It's just an extra header/footer, similar to having meta http-equiv tags. Because it helps limited HTTP clients like JSONP, many web APIs already use this form, but they all use different syntax, which is the problem this "standard" is addressing.

nexneo• 15 years ago

Agree, it claims to be simple while not being consistent, also GET /post.json have invalid JSON in example.

samstokes3• 15 years ago

Something like this makes sense for JSONP, where you can't use HTTP status codes because the handler for the JSONP response doesn't get called at all if the status code is anything other than 200. In this case embedding a "status" field in the response is necessary to communicate errors.

prodigal_erik2• 15 years ago

If an ill-conceived client sends HTTP requests yet drops HTTP status codes on the floor, I have no doubt that coddling it by also breaking the server (200 OK, {"status":"fail"}? wtf?) will catch on despite being an amazingly bad idea. This is why we can't have nice things.

clarkevans• 15 years ago

With CORS (http://www.w3.org/TR/cors/) is JSONP even needed?

johns• 15 years ago

And you can pitch the .json extension with proper content negotiation.

Accepts: application/json

wladimir• 15 years ago

Indeed. If you really need layer upon layer of abstraction, why not go back to the XMLRPC protocols?

The charm of JSON, to me, is its simplicity: that it can run on a bare HTTP server without worrying about dispatching, using a special library with a schema to strictly format responses, and so on.

sdizdar• 15 years ago

I'm not sure but there is difference between: 1) an application server accepts client request but fails to execute it, so client gets an error via JSON and 2) something on server side (HTTP server or application server or firewall) fails to receiver/accept client's request thus client gets back some HTTP error code. Maybe people like this way becasue in complex systems there is always difference between failure to deliver and understand the request and error during execution of the request.

drdaeman• 15 years ago

In a perfect world, /posts/ should JSON when requested when text/json is the most preferred format in HTTP Accept header.

yaxdotcom• 15 years ago

Sure, HTTP status codes should be used. But they aren't enough to communicate application-specific messages from an app backend to an AJAX front-end. For example, AJAX on the browser might submit a form and the server returns a 422 (HTTP validation error status code). How will you be able to inform the user that the "email address must contain @" or "foobar is not an acceptable name"? You need to consume some JSON that has a payload of application-specific status messages.

I don't know if this proposal is optimal (smarter guys than me can decide that). But I know that a standard way of communicating application-specific errors would be a big step forward.

A year ago I searched for an adequate in-place editing plugin for Rails that didn't require major surgery to provide error messages to the user. I was surprised at the complexity required to handle a simple error condition. Usually Rails has all the goodness baked in but it seems application-specific status messages with JSON are out of scope. I asked "How to show server errors in Rails with JSON and jQuery" [1] on Stack Overflow and it's received more views than any other question I've ever asked.

[1] http://stackoverflow.com/questions/2489567/how-to-show-serve...

adamjernst• 15 years ago

Who said you can't include an entity body with a 422 status? e.g.:

HTTP/1.1 422 Unprocessable Entity

{"error": "email address must contain @", "applies_to": "email_field"}

fizx• 15 years ago

Congrats, you just re-invented SOAP!

xal• 15 years ago

My thoughts exactly. This whole proposal induces a serious bout of eye rolling.

orls• 15 years ago

Exactly. I am constantly amazed at how oftem people tack the word REST onto things that are clearly not RESTful, and in some cases (like this one) specifically unRESTful.

Please, people: REST does not simply mean "HTTP is involved somewhere".

tybris3• 15 years ago

I think many are overlooking the fact that this is already common practice. This spec. is just trying to make the practice less bad, not worse.

http://code.google.com/apis/websearch/docs/#fonje

https://www.dropbox.com/developers/docs

DjDarkman• 15 years ago

Why not just return NULL on failure and the data object on success? in most cases that will work, in some cases it will not be enough, but why add redundant data to all responses?

dsl2• 15 years ago

It appears there is no way to contact the author for feedback. This is not how specs work.

dsl2• 15 years ago

Nevermind, this was authored 2 years ago and appeared to gain no traction. http://labs.omniti.com/labs/jsend/wiki/WikiStart?action=diff...

sajidnizami• 15 years ago

This is exactly what SOAP tried to do. I suggest sticking to HTTP Status codes.

hiroprot• 15 years ago

The one thing I could see this being useful for is standardizing pagination for large result sets. Ideally, the server would return meta pagination information that includes total number of results, offset, limit, etc.

Unfortunately, this spec doesn't address that at all as far as I can tell :(

Raphael• 15 years ago

This is not JSON. I don't know what it is.

        { "post" { "id" : 1, "title" : "A blog post", "body" : "Some useful content" } }

postwait• 15 years ago

Enjoying the discussion. The argument that HTTP status codes are "good enough" is one perspective. While I don't buy into everything in the "spec" proposed here, I think having application specific errors that make more sense is reasonable.

In response to there being no method of feedback, looks like the mailing list is linked up now: http://lists.omniti.com/mailman/listinfo/jsend-users

While I might no agree with everything presented in the project, I do agree that it is somewhat arbitrary (and certainly complex) mapping HTTP status codes into every JSON API.

JSend: a specification for how JSON responses should be formatted

Related Stories