[stilkov]

First, I think it's awesome that you guys are documenting this for others to re-use, whether it ends up being the one true format or not. Having options to choose from is doubtlessly good.

Some thoughts:

1. I'm not sure about the name. There will definitely many JSON APIs that don't use (your) JSON API for a long time, even if this becomes hugely popular. I don't see how this will not lead to avoidable confusion in the future. Given that it's very document-centric, why not use something like "JSON Doc API" or similar?

2. In the ID approach, why are the base URIs the client needs to know about not always discoverable, e.g. using standard link relations? Or phrased differently, why would I ever not want to use the "URL Template Shorthands" approach mentioned later?

3. Why use application/json and not something more specific? I can see some reasons, but would be interested in yours.

4. 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?

5. If I use a POST to create something, why don't I get a 201 Created with a Location header?

6. I'd suggest to upgrade the "MAY" for caching to a "SHOULD".

/edited to match @steveklabnik's numbers

[steveklabnik]

1. All media types are 'document centric.' And real REST APIs serve up documents. So seems fine to me. Also, IANA does not have a 'api+json' type registered (until I did so last night), so the name isn't taken.

2. If you're transitioning _to_ this kind from some sort of older kind. Remember, this is extracted from real, working software; it's not some sort of thing we imagined up. Not everyone is super on the hypermedia bandwagon yet, and some will need to transition kind of slowly.

3. I filed for 'appplication/vnd.api+json' yesterday, and so we'll be changing the document as soon as the IANA gets back to me.

4. You could, in theory. Allowing PUT seems fine, it just doesn't often seem to be the case, so we didn't include it. I wouldn't mind having that in there.

5. You should be, this is an oversight.

6. That's very possible.

[stilkov]

> 1. All media types are 'document centric.'

What I meant is that this is a particular kind of backend API, a very "model-centric" one. Nothing wrong with that, I just don't think this is the one and only kind and thus should take on the generic name.

> 2. If you're transitioning _to_ this kind from some sort of older kind.

Understood. Maybe an approach is to allow for this to specified optionally, with the fallback of being hard-coded if it's not present?

[steveklabnik]

I think that the examples appear to be a 'model-centric' one, because we're trying to reach people that build very model-centric sites as of now, but resources can be anything, so I don't think that it's super specific. This is a good thing to think about though.

> with the fallback of being hard-coded if it's not present?

See above for some other good stuff about the IDs that wycats knew that I wasn't as current on.

[wycats]

> 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.

[stilkov]

> You can think of the ID-based approach as just coming with a set of default URL templates in a top-level rel.

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?

[steveklabnik]

I've filed an Issue for you about PUT: https://github.com/json-api/json-api/issues/4