Simplify @path handling

[Geod24]

• Make @rootPathAttribute the default: it just scales better, there is rarely a point in having multiples interfaces at the root.
• Kill RootPathAttribute and use PathAttribute only instead: There was no real difference between @rootpath and @path, as they were mutually exclusive (path on method, rootPath on interface) and had the same behavior (e.g. they are always relative). This will obviously make user code less error-prone.
• Communicate the settings to the sub-interface.

[Geod24]

Ping @Dicebot as we discussed it.
@s-ludwig : Why is RestInterfaceSettings a class ? Shouldn't it be a struct ?

[s-ludwig]

Make @rootPathAttribute the default: it just scales better, there is rarely a point in having multiples interfaces at the root.

You mean @rootPathFromName? I don't agree here. This would be a silent breaking change and for what it's worth, all of my web interfaces currently have the default path of "/". We can't make this change like this without a deprecation path, but I also think that making the path inference explicit is the better idea. It just doesn't seem obvious to me that the type name would automatically become part of the path. Is that possibly different for people coming from certain other web frameworks?

Deprecation of @rootPath sounds fine, though.

Why is RestInterfaceSettings a class ? Shouldn't it be a struct ?

It's just to be consistent with all other *Settings types in the library (I think that HTTPServerSettings was the first - not really sure why I made it a class at the time). There are some low priority pros and cons for either side, but in the end none of them matters much, so I wouldn't want to go through the hassle and change everything now.

[Geod24]

You mean @rootPathFromName? I don't agree here. This would be a silent breaking change and for what it's worth, all of my web interfaces currently have the default path of "/". We can't make this change like this without a deprecation path, but I also think that making the path inference explicit is the better idea. It just doesn't seem obvious to me that the type name would automatically become part of the path. Is that possibly different for people coming from certain other web frameworks?

Yes, I meant @rootPathFromName.
I'm aware of the breaking change, and that's also a problem I considered. I couldn't find any "perfect" solution, beside deprecating un-marked interface in one release, then removing @rootPathFromName in the next, before deprecating it few releases later (but it's rather annoying on a user POV, but probably better).

As per why I want it to be the default :
The REST code generator is, ATM, a kind of gloryfied RPC system IMO.
Usually when you have a REST interface (I think Github's one of the best example), you have 2 kinds of "objects": a ressource, and a collection. Examples of collections are /users/, /posts/ (for a blog), /comments/, /organizationName/ (in case of Github). In those collections, you must have ressources (OFC your collection can be empty).
However, in vibe.web.rest, such construction is neither enforced, nor "easy" to do. It's doable, but there's a lot of gotchas. One of them is @rootPathFromName, as it's an opt-in strategy to this kind of design.

Again, another possibility is to deprecate un-annotated interface for X releases / X time.

It's just to be consistent with all other *Settings types in the library [...]

Ok, makes sense.

[Geod24]

Rebased.

[s-ludwig]

You are right that collection/object handling still needs to be improved. I had some ideas for that, but have to think about this again to remember the details. But please let's leave this as a separate concern for now, because deprecating @rootPath is good and doesn't really depend on the by-name change.

One thing regarding @rootPath: before marking it as deprecated it should just get a doc comment "Scheduled for deprecation - please use $(D @path) instead.(I need to get that written down somewhere). Directly going todeprecated` is always annoying during the transition phase from one version to another.

[Geod24]

You are right that collection/object handling still needs to be improved. I had some ideas for that, but have to think about this again to remember the details.

I'd be interested to know, when you have time to write them down (unrelated: did you get my email?).

For the deprecation, I agree, I just didn't like the double-deprecation (we ask to use rootPathAttribute, then we remove it).

Is this new version better ?

[Geod24]

One thing regarding @rootPath: before marking it as deprecated it should just get a doc comment "Scheduled for deprecation - please use $(D @path) instead." (I need to get that written down somewhere). Directly going to deprecated is always annoying during the transition phase from one version to another.

I'm not sure I understand your point. The point of deprecated is to have a nice way to tell your users that something is going to break. Most users won't bother to look the doc up on each release, especially something as basic as `@rootPath.

This policy is similar to what Druntime/Phobos use to do. But now they're going straight to deprecated because you can give a message with deprecated.

[s-ludwig]

Is this new version better ?

What I meant was that I'd like to exclude the @rootPathFromName change from the PR until we have reached a final conclusion. We can get the @path<->@rootPath change in now, though (with the deprecated <-> "scheduled for deprecation" change).

I'm not sure I understand your point.

A typical situation is that you have a project with dependencies to several libraries. Now it may easily be the case that library A only works with vibe.d 0.7.22, but library B requires 0.7.23. If we now immediately deprecate something in 0.7.23, there is no way to get a clean build with up-to-date dependencies. Including an additional "soft deprecation" step at least alleviates this issue.

[Geod24]

Updated.

[s-ludwig]

This paragraph should get removed for this PR.

[Geod24]

Update.

[s-ludwig]

Thanks, LGTM!