Include global parameters in the REST spec

[gmarz]

Currently, global parameters like source and filter_path aren't included in the spec since it's implied that they exist on all APIs, and so defining them on all endpoints becomes unnecessarily repetitive/redundant.

However, I think it's useful to keep a definition of them somewhere other than the documentation, since after all...they are still part of the REST API. This is especially useful for the .NET client, since we rely on the spec to generate the respective C# methods for each query parameter. Without them defined, we have to modify our code generator to include them manually.

I'm not sure how this would fit into the current spec since we define query parameters on a per endpoint basis...but we could think of something. Maybe a single _global.json file?

Just a thought. If others agree that this is a good idea, I'd be happy to devise some solution.

[clintongormley]

+1

[javanna]

+1

[clintongormley]

@gmarz do you still want this?

[javanna]

I think we should do this, the global.json idea was ok with me. Does anybody at @elastic/es-clients have other ideas?

[gmarz]

I opened #22569. I opted for _global rather than global to signal that it's not an actual endpoint. Open to any suggestions.

[karmi]

What if, instead of _global.json, we had something like _common.json (or similar), which could list not only global URL parameters, but also other things like that in the future?

[javanna]

I have no opinion on global vs common, they both sound good to me.

[gmarz]

I'm also good with _common.json. @karmi what other things do you see us adding in the future other than query params?

[karmi]

@gmarz, not really sure, probably just a case of my regular "just in case" condition :)

[gmarz]

@karmi 👍 I've updated the PR and renamed it to _common.