Adding RestAPI design with backward compatiblity support. (#16)

INSTALLING.md

@@ -20,7 +20,7 @@ _Example_: For Linux platform.
 
 Checkout, build and install the plugin.
 
-_Example_: Install Anomaly Detection(Job Scheduler plugin which is a dependency).
+_Example_: Install Anomaly Detection and Job Scheduler plugins.
 
 ```
 ~/OpenSearch (main)> git clone https://github.com/opensearch-project/job-scheduler.git

UPGRADING.md

@@ -5,7 +5,9 @@ These are all the steps to upgrade plugins to work with OpenSearch and OpenSearc
 - [OpenSearch Plugins](#opensearch-plugins)
    - [Building](#building)
    - [Naming Conventions](#naming-conventions)
-   - [Settings Backwards Compatibility](#settings-backwards-compatibility)
+   - [Backwards Compatibility support](#backwards-compatibility-support)
+    - [Settings Backwards Compatibility](#settings-backwards-compatibility)
+    - [RestAPIs Backwards Compatibility](#rest-apis-backward-compatibility)
 - [OpenSearch Dashboard Plugins](#opensearch-dashboard-plugins)
    - [Building](#building)
    - [Naming Conventions](#naming-conventions)
@@ -16,7 +18,7 @@ These are all the steps to upgrade plugins to work with OpenSearch and OpenSearc
 
 1. Consume artifacts from your dependencies, including OpenSearch, see [BUILDING](BUILDING.md).
 2. Change the namespaces from `org.elasticsearch` to `org.opensearch`. Use the naming convention below.
-3. Consume dependencies with OpenSearch/Dashboards 1.0.0. Continue using `org.elasticsearch` dependencies for `securemock`, `mocksocket` and `jna-build`.
+3. Consume dependencies with OpenSearch/Dashboards 1.0.0-beta1. Continue using `org.elasticsearch` dependencies for `securemock`, `mocksocket` and `jna-build`.
 4. Ensure CI works end-to-end, build and test your plugin.
 5. Report all runtime failures of OpenSearch to [OpenSearch Issues](http://github.com/opensearch-project/opensearch/issues) and runtime failures of plugins in plugin repositories.
 
@@ -37,7 +39,21 @@ The following naming convention has been adopted for Elasticsearch.
 
 See below for Kibana-related naming conventions.
 
-#### Settings Backwards Compatibility
+#### Backwards Compatibility support
+
+There are a bunch of items to think about and support backwards compatibility.
+
+* Renaming, and Backwards Compatibility for Settings
+* Renaming, and Backwards Compatibility for Rest APIs
+* Renaming Namespaces (e.g. `com.amazon.opendistroforelasticsearch` to `org.opensearch`) - TODO
+* Renaming Classes, Methods, Variables - TODO
+* Renaming Remaining Identifiers (e.g. `Opendistro` to `OpenSearch`) - TODO
+* Renaming, and Backwards Compatibility for Indices - TODO
+* Run in a backwards compatible way on top of OpenSearch 1.0 that has joined an ES 7.10.x cluster - TODO
+* Run in a backwards compatible way on top of OpenSearch 1.0 that has joined an ODFE 1.13.x cluster - TODO
+* Drop in replacement for the Opendistro version 1.13 of the plugin - TODO
+
+##### Settings Backwards Compatibility
 
 1. Assuming your settings live in a single class, make a copy of that class and prepend `LegacyOpenDistro` to the copy. Do not rename the settings here in the legacy class. For example:
 
@@ -61,7 +77,6 @@ See below for Kibana-related naming conventions.
                "opendistro.jobscheduler.request_timeout",
                TimeValue.timeValueSeconds(10),
                Setting.Property.NodeScope, Setting.Property.Dynamic, Setting.Property.Deprecated);
-
    }
    ```
 
@@ -91,7 +106,6 @@ See below for Kibana-related naming conventions.
             "opensearch.jobscheduler.request_timeout",
             LegacyOpenDistroJobSchedulerSettings.REQUEST_TIMEOUT,
             Setting.Property.NodeScope, Setting.Property.Dynamic);
-
    }
    ```
 
@@ -129,6 +143,81 @@ See below for Kibana-related naming conventions.
 
 See [job-scheduler#20](https://github.com/opensearch-project/job-scheduler/pull/20) for an example.
 
+#### Rest APIs Backward Compatibility
+
+All APIs which have to be migrated can follow this design.
+From here on the doc will be focussed on an ODFE plugin as an example.
+
+1. All plugins extend `BaseRestHandler` class to implement their own RestAPIs.
+2. All the existing APIs with `_opendistro` should be supported but for maintenance mode only.
+3. All new APIs will be implemented with `_plugins` as defined in the [Naming Conventions](./CONVENTIONS.md).
+4. The method `replacedRoutes()` is overriden and this should now have both `_opendistro` and `_plugins` APIs.
+    ```java
+    public static final String LEGACY_AD_BASE = "/_opendistro/_anomaly_detection";
+    public static final String LEGACY_OPENDISTRO_AD_BASE_URI = LEGACY_AD_BASE + "/detectors";
+    public static final String AD_BASE_URI = "/_plugins/_anomaly_detection";
+    public static final String AD_BASE_DETECTORS_URI = AD_BASE_URI + "/detectors";
+
+    @Override
+    public List<ReplacedRoute> replacedRoutes() {
+        return ImmutableList
+            .of(
+                // delete anomaly detector document
+                new ReplacedRoute(
+                    RestRequest.Method.DELETE,
+                    String.format(Locale.ROOT, "%s/{%s}", AnomalyDetectorPlugin.AD_BASE_DETECTORS_URI, DETECTOR_ID),
+                    RestRequest.Method.DELETE,
+                    String.format(Locale.ROOT, "%s/{%s}", AnomalyDetectorPlugin.LEGACY_OPENDISTRO_AD_BASE_URI, DETECTOR_ID)
+                )
+            );
+    }
+   ```
+5. Add new tests to cover both old and new APIs.
+    ```java
+    public void testBackwardCompatibilityWithOpenDistro() throws IOException {
+        // Create a detector
+        AnomalyDetector detector = TestHelpers.randomAnomalyDetector(TestHelpers.randomUiMetadata(), null);
+        String indexName = detector.getIndices().get(0);
+        TestHelpers.createIndex(client(), indexName, toHttpEntity("{\"name\": \"test\"}"));
+
+        // Verify the detector is created using legacy _opendistro API
+        Response response = TestHelpers
+            .makeRequest(
+                client(),
+                "POST",
+                TestHelpers.LEGACY_OPENDISTRO_AD_BASE_DETECTORS_URI,
+                ImmutableMap.of(),
+                toHttpEntity(detector),
+                null
+            );
+        assertEquals("Create anomaly detector failed", RestStatus.CREATED, restStatus(response));
+        Map<String, Object> responseMap = entityAsMap(response);
+        String id = (String) responseMap.get("_id");
+        int version = (int) responseMap.get("_version");
+        assertNotEquals("response is missing Id", AnomalyDetector.NO_ID, id);
+        assertTrue("incorrect version", version > 0);
+
+        // Get the detector using new _plugins API
+        AnomalyDetector createdDetector = getAnomalyDetector(id, client());
+        assertEquals("Get anomaly detector failed", createdDetector.getDetectorId(), id);
+
+        // Delete the detector using legacy _opendistro API
+        response = TestHelpers
+            .makeRequest(
+                client(),
+                "DELETE",
+                TestHelpers.LEGACY_OPENDISTRO_AD_BASE_DETECTORS_URI + "/" + createdDetector.getDetectorId(),
+                ImmutableMap.of(),
+                "",
+                null
+            );
+        assertEquals("Delete anomaly detector failed", RestStatus.OK, restStatus(response));
+   }
+   ```
+6. Add documentation for the new APIs. For example, [documentation-website](https://github.com/opensearch-project/documentation-website/blob/main/docs/ad/api.md)
+
+See [anomaly-detection#35](https://github.com/opensearch-project/anomaly-detection/pull/35) for an example.
+
 ### OpenSearch Dashboard Plugins
 
 #### Building
@@ -154,4 +243,4 @@ See [job-scheduler#20](https://github.com/opensearch-project/job-scheduler/pull/
 | `Kib`    | `Osd`                   |
 | `KIB`    | `OSD`                   |
 
-See [anomaly-detection-dashboards-plugin#1](https://github.com/opensearch-project/anomaly-detection-dashboards-plugin/pull/1) for an example.
+See [anomaly-detection-dashboards-plugin#1](https://github.com/opensearch-project/anomaly-detection-dashboards-plugin/pull/1) for an example.