Say I have a lot of page with ajax. Is there any convention or recommendation on the format/structure of an ajax response? Namely, if there's an error, a server returns http status 4xx or 5xx and... what structure should a json response have? Should it be with the root-level key "errors"? What structure should an an item of "error" have? Or should there be a simple array of errors? What if there was a single error?

The same goes for a successful response: should there be a root-node "data", for example? And so on.

I'm aware about jsonapi.org, for example, but it's for public REST APIs, whereas I use ajax only across my website and therefore probably I'm the only user and it should be simpler. Although, yes, possibly it can be used from other websites as well by other users.

  • en.wikipedia.org/wiki/JSON-RPC – Idan Arye Apr 20 '17 at 9:00
  • @IdanArye, what does ajax have to do with that? and why, only because you think they're related? moreover, what if I use xml for ajax? – Dorion Apr 20 '17 at 9:02
  • You asked for a format for the server response. JRPC-RPC is such a format, and it's relatively simple and well supported. If you used XML you could have used XML-RPC – Idan Arye Apr 20 '17 at 16:09
  • @IdanArye, JSON-RPC is not such a format. JSON-RPC is a format for RPC. – Dorion Apr 20 '17 at 23:34

Asynchronous JavaScript and XML has largely been abandoned in favour of JSON and 'REST' although full REST is rarely implemented.

This means sending error codes in the HTML response code and a plain text message in the body as you would see with a normal failed HTTP request.

This has several downsides, control flow by exception, ambiguous error codes. But the advantage of being simple and not complicating your response object with a possible error state.

Where you have a complex, not success, result to return such as input validation, I suggest structuring your return object to specifically include those results as a success rather than attempt to cram them into an error message. eg

HTTP 200
        "validationMessages" : [
            "username already in use",
            "password must contain at least one capital letter"

You can see this object works equally well for both success and failure, leaving the HTTP code for 'real' exceptions where the code errors or the server fails in some way

  • my question isn't what one would suggest me, but what's the most commonly used, even if there's no official standard for it. what's your advice based on? who else follows this approach? moreover, "validationMessages" is a very specific case of an error, there're even no names of the fields and it's not right, it should better contain an object or array of objects instead of just string. – Dorion Apr 21 '17 at 8:02
  • well I have provided both. the published (and popular) standard (REST) and what I consider from my experience to be a good solution to the 'complex error' case (with simple example) which is not well served by the standard – Ewan Apr 21 '17 at 8:07
  • because its a success response, the object is defined by your api rather than the protocol, so you can define specific responses for each endpoint – Ewan Apr 21 '17 at 8:08
  • This means sending error codes in the HTML response code --> this also means that an http response status shouldn't be 2xx in case of an error. – Dorion Apr 21 '17 at 8:09
  • yes, but you get to define what an 'error' is. so where your api has a complex response, define it as a successful api call which returns the structured response saying what the result of that call was. in this case, we didnt add the user because of x,y, z – Ewan Apr 21 '17 at 8:12

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.