Provide configuration to allow for a RESTful JSON interface (unwrapped objects).

[pyeve]

Provide configuration to allow for a RESTful JSON interface (unwrapped objects).

[nicolaiarocci]

Yeah current responses are a bit verbose and that's because of XML as you figured out. But not only that, it is also because of HATEOAS constraints. The collection endpoint (/works/) provides another element not provided with your snippet: links. If I was to 'flatten' the stream, the only option would be to replicate the parent and collection link item for each element in the array, which wouldn't be a smart way to save on bandwith. And also, what about the nextand previous links? They wouldn't make any sense inside an item element. Don't get me wrong, I would love to simplify the output stream, but not at the cost of renouncing to HATEOAS. Let's see if we can come up with a good compromise perhaps?

[lukateake]

I understand the HATEOAS constraint and would "hate" to lose it, @nicolaiarocci. I'll clean up the extra info in my Models' superclass parse() method to make the response BB compliant.

Also, I hate to trouble you further but could you pump up the Eve demo sample data to the point where it triggers pagination? Thanks in advance!

[nicolaiarocci]

Would you please add a issue to the eve-demo repo about that? - thanks!

[nicolaiarocci]

I now have an experimental branch where you can set HATEOAS = False in settings.py. By disabling HATEOAS you get 'flat' responses to your GET requests, as in the examples posted by @lukateake at the beginning of this thread. So, at least while I am playing with it, I am reopening this issue (and labeling it 'feature request').

[nicolaiarocci]

Check out the new branch optional-hateoas (https://github.com/nicolaiarocci/eve/tree/optional-hateoas) and let me know if everything works/behaves as desired/expected. I'd appreciate some feedback before merging with the master branch. @lukateake

[andreineculau]

@nicolaiarocci a bit of late response on this

Seeing "response" inside the payload of a response is disturbing to my mind.
Links is not something outside the response at all - see https://groups.google.com/d/topic/api-craft/XnpDEm94ybI/discussion

My design of a collection-resource response is

{
 "items": [],
 "links": []
}

Have a look at http://docs.starbucks.apiary.io/ to get an overview picture.

PS: as for each item carry-ing a link, have a look at https://groups.google.com/d/msg/api-craft/1CtOuEF8Gls/Lxndx0alV7cJ

PPS: Sorry for the scarce comments - I just wanted to give you feedback a long time ago, but delayed it due to lack of time. I'll try to make time and review Eve in detail, and then maybe you'll see where I'm coming from. It's a great effort btw!

[andreineculau]

One more thing - I know you also tweeted to ask whether to drop XML or not.
You could watch http://www.youtube.com/watch?v=BNrGkFq6M9U and see one opinion on XML.

But beyond what people prefer/use - without even looking at Eve's source code - Eve should NOT be designed based on the serialization format. It should be agnostic of XML, JSON, YML, ProtoBuffers, etc.

[andreineculau]

Offtopic, but related to previous comment - same agnostic perspective should go for "filtering & sorting". That part is much more of a Eve plugin, than a Eve core functionality imho

[drdaeman]

Here's a problem to consider. HATEOAS (thus, "truly" RESTful) explicitly requires hyperlinking. Fielding said so. JSON by itself has no such symantic, neither do PBs.

In case of JSON, there's an emerging standard, devoted to solving this problem, called HAL, but that's HAL¹, not JSON — JSON is just an underlying serialization format. I'm not aware of any hyperlinking-capable standards for other serialization formats.

Another kind of problem arise when PATCH HTTP method kicks in. There's a standard on patch format for XML, but I'm not aware about any for JSON or, say, YAML. This is not much of a problem if all resources are simple dictionaries with string keys and immutable scalar values (so they could only be replaced), but with more complex data structures it's a bit of headache.

When talking about format agnosticism, I believe those points should be taken into consideration.

---

¹) I suggest taking a look at HAL. As for the original issue, it's HATEOAS, but, for example, it's compatible with Backbone by means of Backbone.HAL plugin.

[andreineculau]

@drdaeman not sure I get the point you want to make

re: JSON Patch http://tools.ietf.org/html/draft-ietf-appsawg-json-patch-09 , but I don't know how PATCH came into the picture

re: HATEOAS - you can achieve it even if the response media-type is not hypermedia aware via the Link header http://tools.ietf.org/html/rfc5988

The discussion is too long but there is a community that wants HAL, Siren, collection+JSON, etc meaning generic hypermedia formats (or generic PATCH formats), and there is a community that goes with vendor media-types that define their own semantics, hypermedia aware or not.

But no matter the direction (exposing HATEOAS via headers, via generic media-types, or via vendor media-types), they are all correct, and that's why I said Eve could (it's Nicola's decision to maybe change this into "should") be format agnostic. It could provide some serializers by default, but could also allow the user to feed in a custom serializer that takes response headers, response "data", and response links and puts the links wherever and however it sees fit.

[nicolaiarocci]

Guys, thanks for the awesome feedback.

I'm going to remove the responseroot item, at least from the JSON payload if not completely. The main reason why it is there in the first place, is that XML requires a root node (at least if you want it to pass any kind of validation - of course one can just ignore the constraint; most XML parsers will process it without a glitch). Also, it seemed appropriate to have a root item since we were going to always have at least two child nodes (resource items and links). Since a) I tend to favor simplicity of verbosity, b) I'm going to make HATEOAS an option enabled by default (no need for child nodes if disabled) and, c) don't see why XML constraints should influence Eve payloads... I'll just get rid of it. I really like @andreineculau JSON layout, and I'll probably go in that direction. The XML renderer will take care of adding a root node as required.

In time, I'd also like to add an option to enable/disable JSON/XML rendering via the configuration file.

@andreineculau can you please open a different issue about making filtering, sorting & paging optional?

@drdaeman I will look into HAL.

Fire away!

[nicolaiarocci]

nicolaiarocci@7a0df14

• no more response item in JSON payloads;
• standardized list & key names when serving GET requests.

In light of this and to keep everything as simple as possible, for the time being I'm not going to make HATEOAS optional. If you think it should be, please let me know.