JSend: a specification for how JSON responses should be formatted(labs.omniti.com)
labs.omniti.com
JSend: a specification for how JSON responses should be formatted
http://labs.omniti.com/labs/jsend
10 comments
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.
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.
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.
Many modern-day streaming protocols are built on top of HTTP purely because firewalls don't block it and proxies can forward it. Obviously that's a terrible idea from a performance point of view, but it's a fact of life that things are broken and we can deal with it by moving up the protocol stack.
Feel free to try and make (400 Bad Request, {"details": "whatever"}) work when your Javascript code is injected into someone else's code running on their own domain. If you can - and not require users to be using a particular browser version - you will make mashup and browser extension authors very happy.
In the mean time, coddling is required.
This is indeed why we can't have nice things.
In the mean time, coddling is required.
This is indeed why we can't have nice things.
If I really wanted to cater to such insanely reckless third parties who can't proxy through their own servers, I'd leave my real services unchanged (so they can still be consumed by non-broken clients) and add a js proxy service that can call any of my real services, and return a response with js that stuffs a description of the real response into an object supporting the XMLHttpRequest interface (especially including getResponseHeader(), status, and statusText). That way the caller can treat XHR as a uniform API for handling responses, even for those cases where they had to resort to an ugly hack rather than XHR to actually get the request on the wire.
With CORS (http://www.w3.org/TR/cors/) is JSONP even needed?
Once all browsers in use by everyone support CORS: no.
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"?)
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"?)
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.
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.
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.
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.
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.
And you can pitch the .json extension with proper content negotiation.
Accepts: application/json
Accepts: application/json
In a perfect world, /posts/ should JSON when requested when text/json is the most preferred format in HTTP Accept header.
Agree, it claims to be simple while not being consistent, also GET /post.json have invalid JSON in example.
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...
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...
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"}
HTTP/1.1 422 Unprocessable Entity
{"error": "email address must contain @", "applies_to": "email_field"}
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
http://code.google.com/apis/websearch/docs/#fonje
https://www.dropbox.com/developers/docs
Congrats, you just re-invented SOAP!
My thoughts exactly. This whole proposal induces a serious bout of eye rolling.
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".
Please, people: REST does not simply mean "HTTP is involved somewhere".
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.
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.
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 :(
Unfortunately, this spec doesn't address that at all as far as I can tell :(
It appears there is no way to contact the author for feedback. This is not how specs work.
Nevermind, this was authored 2 years ago and appeared to gain no traction. http://labs.omniti.com/labs/jsend/wiki/WikiStart?action=diff...
This is exactly what SOAP tried to do. I suggest sticking to HTTP Status codes.
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?
This is not JSON. I don't know what it is.
{ "post" { "id" : 1, "title" : "A blog post", "body" : "Some useful content" } }