Rename request and response types

[delvedor]

As titled.

TODO:

• This pr makes use of import aliases, which could break the script to fix the imports. Need to investigate.

[swallez]

Having played a bit with this PR in my IDE, and after a bit of thinking, I'm not sure renaming everything to just Request and Response is a good idea: it makes navigating in the specification harder, as there are now so many items with the same name.

I'm using IntelliJ as my IDE. Navigating to a particular declaration can be done in 3 ways: by searching for a symbol, by searching by a file name, of by navigating the tree. The latter is much slower as it requires either the mouse or lots of arrow keystrokes.

Renaming all requests and responses to just Request and Response basically breaks navigation by symbol search. In its current form the PR still has distinct file names for them (e.g.BulkRequest.ts), but I guess we won't keep these names, thus breaking filename search too.

So what about letting spec writers use a naming of their choosing for endpoint request and response, that is meaningful in the context of a namespace?

I actually would go as far as enforcing uniqueness in a namespace, i.e. extend the uniqueness constraint we have defined for _types also to requests and responses in that namespaces, including additional structures specific to an endpoint.

This allows code generators to flatten all identifiers of a namespace into a single module if they want, without having to implement a scheme to create unique names for requests and responses.

And if we don't want to allow free-form naming, we can also enforce a convention that requires request and response names to be prefixed by the endpoint name (without the namespace), e.g. cluster.health would have HealthRequest and HealthResponse.

[philkra]

So what about letting spec writers use a naming of their choosing for endpoint request and response, that is meaningful in the context of a namespace?

Wasn't that what we agreed on in the first place? Otherwise, we'll struggle to have any language idiomatic's. The spec yield should sufficient already to make the call on defining custom naming patterns for request & response.

[delvedor]

basically breaks navigation by symbol search.

I'm not sure what you mean, with VSCode if I do cmd+click on an imported definition with a import alias, I get the original definition as expected.

So what about letting spec writers use a naming of their choosing for endpoint request and response, that is meaningful in the context of a namespace?

This is exactly what we had before refactoring the spec with the rest-api-spec namespaces, and it was causing issues down the road. This new strategy is stricter and won't allow any inconsistency with naming. For example:

/indices
    /put_mapping
        /def.ts => `Request` (type name)

Since we are guaranteeing name uniqueness within a folder, a language generator could create the type in any way the target language needs. It can be a deep namespaced import, eg Indices.PutMapping.Request, a less deep namespaced import, Indices.PutMappingRequest or a completely flat type, IndicesPutMappingRequest. This can be done via the union of the type name and the namespace and it is always guaranteed to work. If we start naming the requests type like the API, eg PutMappingRequest, then either we need to remove the intermediate folder, or we need to force every language generator to surgically rename the types to have nice imports, which I don't think makes a lot of sense.
What I like about the current solution is that it allows you to choose how deep the type definition in the target language should look like. The less work we force language generators to do downstream the better imho.

Finally, I don't believe that the tree navigation is slow, in my opinion is "fast" as it's very straightforward, even for newcomers. For example, you need the cluster health request definition, you know already where it is, 3 clicks away! /cluster/health/{def}.ts.
While if you use only the second part of the API as type name, there is the risk that you find multiple apis. For example you want the ml.inforequest definition, so you search for InfoRequest. You will find at least 4 results, the top level info, ml.info, nodes.info and xpack.info.

[philkra]

LGTM

[philkra]

LGTM