Align parameters syntax with attributes

[pksunkara]

For @zdne to review & merge.

I had all this description about how the old syntax was changed to the new syntax and stuff. Then, I realized that it is not the way we do things in the API Blueprint specification. 😐

We only describe the current syntax, but still offer backward compatibility.

[kylef]

Should this read: "Each of the list items" instead of "Each of the list item".

[zdne]

👍 on @kylef's comment

[zdne]

Also I am not convinced that we should refer to MSON here. Align the syntax yes. But I would not claim it is MSON syntax as there are some gaps such as the required vs. optional or the fact that there are no nested types.

Also explaining URI syntax here without references to MSON would set a great building stone for introducing MSON later...

[zdne]

For @zdne to review & merge.

I think it is OK if @kylef or even @klokane reviews this and merge it (I think it is not really needed to write these addresses )

[zdne]

Please do not refer to MSON here. Explain it without referencing to MSON syntax.

[zdne]

@pksunkara reviewed. Besides @kylef comments I would say we can't really claim the URI parameter syntax IS MSON syntax, because, well, it isn't. Please take the effort and explain the syntax in words without referring to MSON.

[pksunkara]

I would say we can't really claim the URI parameter syntax IS MSON syntax, because, well, it isn't.

I strongly disagree with that. In my opinion, we should want to move URI parameter syntax to MSON syntax (not simply align it but complete move it) because of three things:

1. Few APIs allow arrays to be sent in a query parameter. (Ex: CouchDB API). So, we do want to allow users the option for complex parameter values.
2. We might want to use the URI parameters to improve the Request and/or Response payloads in the future (along with using them in the mock server)
3. Even though parameters won't contain more than 1 or 2 nested levels, I don't want to add a separate description for them and think it is better if we just point the users to MSON. I am saying this because I think it will be easier for the users this way rather than to read different things for parameters and attributes.

[jrep]

@pksunkara : I'm OK with adding fully-MSON parameter descriptions, but if your "move" means "forbid the old way" I would strongly disagree. We are using Blueprint to document legacy, often highly un-RESTful APIs (as well as documenting and developing more RESTful ones). If the Blueprint language should lose the power to do that, we couldn't continue using it.

But I agree with @zdne in that the MSON syntax for parameters must be in place first, before it can be used by reference to explain things.

[pksunkara]

@jrep The old syntax will still be supported even after the move. So, you should not have a worry.

But I agree with @zdne in that the MSON syntax for parameters must be in place first, before it can be used by reference to explain things.

I am sorry but I didn't get what you mean by this.

[jrep]

About "move": OK, I'm satisfied about that.

About "agree with @zdne":

1. You added "You can give an enumeration of possible values using [MSON][] as shown below".
2. Z commented "we can't really claim the URI parameter syntax IS MSON syntax, because, well, it isn't".
3. You responded "I strongly disagree with that", quoting Z's comment as I have done here.

I take Z's comment to mean "at the moment, URI parameter syntax is not MSON. Therefore, at the moment, we shouldn't put in a link that claims that it is MSON." Z's comment doesn't explicitly say whether the fix should be to remove the link (which would, of course, be easy), or to fix up URI parameter syntax to be MSON (as you have advocated, a more difficult but possibly higher goal). I took your "strong disagreement" to mean "it's OK to put the MSON link here, even though URI parameter syntax is not MSON."

Perhaps you meant something lesser, like "this particular detail is already MSON-compatible, so the link is OK in this case." I would disagree with that, for fear of creating the false impression that URI parameter syntax is entirely MSON.

Or, perhaps you meant "I agree that URI parameter syntax is presently not MSON, but I believe we should respond by fixing URI parameter syntax actually to be MSON, at which point this link would be OK." Now that you've reassured me about "move" and backwards compatibility, I'm OK with this philosophical position, but I continue to hold (in agreement, I believe, with Z) that the upgrades to URI parameter syntax should come first, and only when that is complete does this link become OK.

And as background, I'm a little dubious that this upgrade of URI parameter syntax to full MSON-ness is actually practical, so I'd rather not see the link sneak in on mere speculation that MSON-ization will eventually happen.

[pksunkara]

Okay, got it. Thanks for the exaplanation 😄

Firstly, the changes in this PR will get published only after they are implemented in the parser. So

"I agree that URI parameter syntax is presently not MSON, but I believe we should respond by fixing URI parameter syntax actually to be MSON, at which point this link would be OK."

This is what I am trying to do.

I think what @zdne was trying to say is that, "Parameters should not be MSON, just the syntax should resemble a bit of MSON". That statement is what I strongly disagree with. I think it should be completely MSON not just resemblance.

I'm a little dubious that this upgrade of URI parameter syntax to full MSON-ness is actually practical, so I'd rather not see the link sneak in on mere speculation that MSON-ization will eventually happen.

This should not be an issue due to how MSON was implemented in the parser. If we do decide on going the MSON route, there will be no half-measures when implementing the change in the parser.

[zdne]

@jrep thanks for great feedback! I think we are aligned here. Although I have a question: Do you think we should keep the deprecated syntax in the specification (or anywhere else for that matter)? The motivation behind this question is to prevent confusion for readers of older blueprints.

[zdne]

@pksunkara

I strongly disagree with that. In my opinion, we should want to move URI parameter syntax to MSON syntax (not simply align it but complete move it)

Let's do it step by step. First align. Then move it if it will make sense.

Few APIs allow arrays to be sent in a query parameter. (Ex: CouchDB API). So, we do want to allow users the option for complex parameter values.

Aligning the syntax first won't prevent supporting this in a future

We might want to use the URI parameters to improve the Request and/or Response payloads in the future (along with using them in the mock server)

Again, the alignment won't prohibit us from doing this in future.

Even though parameters won't contain more than 1 or 2 nested levels, I don't want to add a separate description for them

Let's not be lazy. Aligning this is actually much easier and safer then referencing MSON. There is way too many exception in MSON that you would have to take care (read document) them than defining the primitives (consider On Of, Include, Inheritance, Nested members).

[zdne]

Two main points here:

1. URI Parameters syntax will remain backward compatible
2. URI Parameter syntax won't be, for the time being, full-blown MSON

[pksunkara]

Updated.

[kylef]

I think this could be a little simpler:

-Each of the list items describes a single URI parameter.
+Each list item describes a single URI parameter.

[zdne]

Looks good to me. Main comment is on explaining members section with regard to the type value of an enum[type]. Please describe it more thoroughly

[pksunkara]

Updated.