refactor: replace payload with body for consistency with OpenSearch API

CHANGELOG.md

@@ -63,6 +63,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - fix bug in `MLCommonClient_client.upload_model` by @rawwar in ([#336](https://github.com/opensearch-project/opensearch-py-ml/pull/336))
 - fix lint issues on main by @rawwar in ([#374](https://github.com/opensearch-project/opensearch-py-ml/pull/374))
 - fix CVE vulnerability by @rawwar in ([#383](https://github.com/opensearch-project/opensearch-py-ml/pull/383))
+- refactor: replace 'payload' with 'body' in `create_standalone_connector` by @yerzhaisang ([#424](https://github.com/opensearch-project/opensearch-py-ml/pull/424))
 
 ## [1.1.0]
 

opensearch_py_ml/ml_commons/model_connector.py

@@ -5,6 +5,8 @@
 # Any modifications Copyright OpenSearch Contributors. See
 # GitHub history for details.
 
+import warnings
+
 from opensearchpy import OpenSearch
 
 from opensearch_py_ml.ml_commons.ml_common_utils import ML_BASE_URI
@@ -14,12 +16,35 @@ class Connector:
     def __init__(self, os_client: OpenSearch):
         self.client = os_client
 
-    def create_standalone_connector(self, payload: dict):
-        if not isinstance(payload, dict):
-            raise ValueError("payload needs to be a dictionary")
+    def create_standalone_connector(self, body: dict = None, payload: dict = None):
+        """
+        Create a standalone connector.
+
+        Parameters:
+            body (dict): The request body, preferred parameter.
+            payload (dict): Deprecated. Use 'body' instead.
+
+        Raises:
+            ValueError: If neither 'body' nor 'payload' is provided or if the provided argument is not a dictionary.
+        """
+        if body is None and payload is None:
+            raise ValueError("A 'body' parameter must be provided as a dictionary.")
+
+        if payload is not None:
+            if not isinstance(payload, dict):
+                raise ValueError("'payload' needs to be a dictionary.")
+            warnings.warn(
+                "'payload' is deprecated. Please use 'body' instead.",
+                DeprecationWarning,
+            )
+            # Use `payload` if `body` is not provided for backward compatibility
+            body = body or payload
+
+        if not isinstance(body, dict):
+            raise ValueError("'body' needs to be a dictionary.")
 
         return self.client.transport.perform_request(
-            method="POST", url=f"{ML_BASE_URI}/connectors/_create", body=payload
+            method="POST", url=f"{ML_BASE_URI}/connectors/_create", body=body
         )
 
     def list_connectors(self):

tests/ml_commons/test_model_connector.py

@@ -31,7 +31,7 @@ def _safe_delete_connector(client, connector_id):
 
 
 @pytest.fixture
-def connector_payload():
+def connector_body():
     return {
         "name": "Test Connector",
         "description": "Connector for testing",
@@ -52,8 +52,8 @@ def connector_payload():
 
 
 @pytest.fixture
-def test_connector(client: Connector, connector_payload: dict):
-    res = client.create_standalone_connector(connector_payload)
+def test_connector(client: Connector, connector_body: dict):
+    res = client.create_standalone_connector(connector_body)
     connector_id = res["connector_id"]
     yield connector_id
 
@@ -64,8 +64,8 @@ def test_connector(client: Connector, connector_payload: dict):
     OPENSEARCH_VERSION < CONNECTOR_MIN_VERSION,
     reason="Connectors are supported in OpenSearch 2.9.0 and above",
 )
-def test_create_standalone_connector(client: Connector, connector_payload: dict):
-    res = client.create_standalone_connector(connector_payload)
+def test_create_standalone_connector(client: Connector, connector_body: dict):
+    res = client.create_standalone_connector(connector_body)
     assert "connector_id" in res
 
     _safe_delete_connector(client, res["connector_id"])
@@ -74,6 +74,15 @@ def test_create_standalone_connector(client: Connector, connector_payload: dict)
         client.create_standalone_connector("")
 
 
+@pytest.mark.parametrize("invalid_body", ["", None, [], 123])
+def test_create_standalone_connector_invalid_body(client: Connector, invalid_body):
+    with pytest.raises(
+        ValueError,
+        match=r"A 'body' parameter must be provided as a dictionary|'body' needs to be a dictionary",
+    ):
+        client.create_standalone_connector(body=invalid_body)
+
+
 @pytest.mark.skipif(
     OPENSEARCH_VERSION < CONNECTOR_MIN_VERSION,
     reason="Connectors are supported in OpenSearch 2.9.0 and above",