If the spec wants to assign special semantics to additional query parameters down the line, that will be impossible if JSON-API APIs are already using these parameters in different ways. Therefore, I propose either:

1. Adding a list of query parameters to the spec that compliant APIs can’t use in their urls. Off the top of my head, that list—which I figure we should make pretty greedy—might include: embed, match, version, search, action, links, signature, access, docs,profile, profiles … anything else?

2. Or, an alternate solution would be to have the user prefix any of their query parameters (i.e. any they’re using that aren’t defined by the spec). This has a couple things going for it:

   1. We can add any query parameter we want down the line, as long as it doesn’t start with the prefix character (which is fine, since we want to avoid prefixing spec keywords anyway)
   2. It makes visible in the url which query parameters are standard and which are non-standard.

   But maybe a downside is it makes the URLs of compliant APIs somewhat uglier (since the user parameters are prefixed)?

Thoughts?

(As an aside: Extensibility questions like the above are what I was trying to raise, with @hhware, in #588. But I think our discussion was somewhat off topic there and perhaps unappreciated, so I apologize. Hopefully now we can discuss extensibility in proper, separate issues. I think this question of how to prepare the spec for the future is important, and while it’s something that the spec authors (@dgeb, @tkellen, @steveklabnik et al) may have discussed in private, it hasn’t basn’t been discussed explicitly on github much.)