[REST Compatible API] Route refactoring

[joegallo]

Related to #51816

Makes Routes RestApiVersion -aware (and RestHandlers RestApiVersion -agnostic). Refactors how Routes are constructed in the case of deprecation or replacement of routes.

---

Some examples of how this affects Rest Actions

Very normal existing rest action, no change on this PR:

public class RestMainAction extends BaseRestHandler {

    @Override
    public List<Route> routes() {
        return List.of(
            new Route(GET, "/"),
            new Route(HEAD, "/"));
    }

[...]

A rest action with a deprecated route, before:

public class RestPostDataAction extends BaseRestHandler {

    @Override
    public List<Route> routes() {
        return Collections.emptyList();
    }

    @Override
    public List<DeprecatedRoute> deprecatedRoutes() {
        return Collections.singletonList(
            new DeprecatedRoute(POST, MachineLearning.BASE_PATH + "anomaly_detectors/{" + Job.ID.getPreferredName() + "}/_data",
            "Posting data directly to anomaly detection jobs is deprecated, " +
                "in a future major version it will be compulsory to use a datafeed"));
    }

[...]

And after:

public class RestPostDataAction extends BaseRestHandler {

     @Override
     public List<Route> routes() {
        return List.of(
            Route.builder(POST, BASE_PATH + "anomaly_detectors/{" + Job.ID.getPreferredName() + "}/_data")
                .deprecated("Posting data directly to anomaly detection jobs is deprecated, " +
                    "in a future major version it will be compulsory to use a datafeed", RestApiVersion.V_8
                ).build()
        );
    }

[...]

A rest action with some replaced routes, before:

public class RestGetUsersAction extends SecurityBaseRestHandler {

    @Override
    public List<Route> routes() {
        return Collections.emptyList();
    }

    @Override
    public List<ReplacedRoute> replacedRoutes() {
        // TODO: remove deprecated endpoint in 8.0.0
        return List.of(
            new ReplacedRoute(GET, "/_security/user/", GET, "/_xpack/security/user/"),
            new ReplacedRoute(GET, "/_security/user/{username}", GET, "/_xpack/security/user/{username}")
        );
    }

[...]

And after:

public class RestGetUsersAction extends SecurityBaseRestHandler {

    @Override
    public List<Route> routes() {
        return List.of(
           Route.builder(GET, "/_security/user/")
               .replaces(GET, "/_xpack/security/user/", RestApiVersion.V_7).build(),
           Route.builder(GET, "/_security/user/{username}")
               .replaces(GET, "/_xpack/security/user/{username}", RestApiVersion.V_7).build()
        );
    }

[...]

[joegallo]

Crucially, these sorts of methods fall out:

         @Override
         public List<DeprecatedRoute> deprecatedRoutes() {
             return [...];
         }

         @Override
         public List<ReplacedRoute> replacedRoutes() {
             return [...];
         }

And now there is only routes().

[joegallo]

@pgomulka 7bb0919 should address your comment w.r.t. imports

[pgomulka]

LGTM, thank you!

[jaymode]

I left a few minor comments, otherwise LGTM.

[joegallo]

Thank you @jakelandis, @jaymode, and @pgomulka for working with me on this one. I'm really happy with where it ended up!

Now to resurrect the _xpack/* APIs under this new mechanism. 😄