| > I'm not sure about the name Good feedback. Many people have said this, and I'm thinking about an alternative. > Or phrased differently, why would I ever not want to use the "URL Template Shorthands" approach mentioned later? You can think of the ID-based approach as just coming with a set of default URL templates in a top-level rel. The primary reason I included it (and I considered not including it), is that it may be easier for servers, when getting started, to adhere to both strict URL naming and skip generating URLs in the JSON serialization layer of their application. I'm working on some tooling for Rails that will pretty much eliminate these considerations, but I weighed ease of server-implementation when I built this. Again, don't think of the ID form as being URL-less, think of it as coming with a default, easy to implement URL template. > Why use application/json and not something more specific? I can see some reasons, but would be interested in yours. Two reasons: (1) Many existing clients and servers already support easy generation of JSON requests and JSON responses. (2) I haven't yet registered an alternative MIME type. > On creation, if I accept the pain of generating an ID on the client and can construct the URI using the template, why can't I use PUT instead of POST? Good point. That seems fine. > If I use a POST to create something, why don't I get a 201 Created with a Location header? Also good point, and an embarrassing oversight on my part. That should be how it works. > I'd suggest to upgrade the "MAY" for caching to a "SHOULD". Hmm. You think a server SHOULD use HTTP caching? RFC terminology is pretty dodgy, but caching really seems more like an optional feature ("One vendor may choose to include the item because a particular marketplace requires it or because the vendor feels that it enhances the product while another vendor may omit the same item") than a strong recommendation ("This word, or the adjective "RECOMMENDED", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course"). Thanks for all the feedback. It was really valuable. |
Then I'd be perfectly happy. But why is the paragraph that mentions exactly this ("... The top-level of a JSON API document MAY have the following keys") in the "URL-Based JSON API" section?
> You think a server SHOULD use HTTP caching?
No, you're probably right - a SHOULD is too strong. I guess my reaction was more negative to the "MAY" in your text about caching than anything else. The caching section (which is currently in the writing document?) doesn't seem to actually add much value beyond what HTTP says anyway. Maybe dropping it is the easiest path?