[Connector API] Add 8.13 docs (#105456)

docs/reference/connector/apis/connector-apis.asciidoc

@@ -29,10 +29,13 @@ Use the following APIs to manage connectors:
 * <<update-connector-configuration-api>>
 * <<update-connector-error-api>>
 * <<update-connector-filtering-api>>
+* <<update-connector-index-name-api>>
 * <<update-connector-last-sync-api>>
 * <<update-connector-name-description-api>>
 * <<update-connector-pipeline-api>>
 * <<update-connector-scheduling-api>>
+* <<update-connector-service-type-api>>
+* <<update-connector-status-api>>
 
 
 [discrete]
@@ -70,7 +73,10 @@ include::set-connector-sync-job-stats-api.asciidoc[]
 include::update-connector-configuration-api.asciidoc[]
 include::update-connector-error-api.asciidoc[]
 include::update-connector-filtering-api.asciidoc[]
+include::update-connector-index-name-api.asciidoc[]
 include::update-connector-last-sync-api.asciidoc[]
 include::update-connector-name-description-api.asciidoc[]
 include::update-connector-pipeline-api.asciidoc[]
 include::update-connector-scheduling-api.asciidoc[]
+include::update-connector-service-type-api.asciidoc[]
+include::update-connector-status-api.asciidoc[]

docs/reference/connector/apis/list-connectors-api.asciidoc

@@ -29,6 +29,15 @@ Returns information about all stored connectors.
 `from`::
 (Optional, integer) The offset from the first result to fetch.
 
+`index_name`::
+(Optional, string) A comma-separated list of data index names associated with connectors, used to filter search results.
+
+`connector_name`::
+(Optional, string) A comma-separated list of connector names, used to filter search results.
+
+`service_type`::
+(Optional, string) A comma-separated list of connector service types, used to filter search results.
+
 [[list-connector-api-example]]
 ==== {api-examples-title}
 
@@ -74,3 +83,25 @@ The following example lists the first two connectors:
 ----
 GET _connector/?from=0&size=2
 ----
+
+An example to list connectors associated with `search-google-drive` data index name:
+
+[source,console]
+----
+GET _connector/?index_name=search-google-drive
+----
+
+
+An example to list all connectors with `sharepoint_online` service type:
+
+[source,console]
+----
+GET _connector/?service_type=sharepoint_online
+----
+
+An example to list all connectors with `sharepoint_online` or `google_drive` service type:
+
+[source,console]
+----
+GET _connector/?service_type=sharepoint_online,google_drive
+----

docs/reference/connector/apis/update-connector-configuration-api.asciidoc

@@ -6,7 +6,7 @@
 
 preview::[]
 
-Updates the `configuration` of a connector.
+Updates a connector's `configuration`, allowing for complete schema modifications or individual value updates within a registered configuration schema.
 
 
 [[update-connector-configuration-api-request]]
@@ -31,8 +31,11 @@ Updates the `configuration` of a connector.
 [[update-connector-configuration-api-request-body]]
 ==== {api-request-body-title}
 
+`values`::
+(Optional, object) Configuration values for the connector, represented as a mapping of configuration fields to their respective values within a registered schema.
+
 `configuration`::
-(Required, object) The configuration for the connector. The configuration field is a map where each key represents a specific configuration field name, and the value is a `ConnectorConfiguration` object.
+(Optional, object) The configuration for the connector. The configuration field is a map where each key represents a specific configuration field name, and the value is a `ConnectorConfiguration` object.
 
 Each `ConnectorConfiguration` object contains the following attributes:
 
@@ -105,41 +108,94 @@ The following example updates the `configuration` for the connector with ID `my-
 ////
 [source, console]
 --------------------------------------------------
-PUT _connector/my-connector
+PUT _connector/my-spo-connector
 {
-  "index_name": "search-google-drive",
-  "name": "My Connector",
-  "service_type": "google_drive"
+  "index_name": "search-sharepoint-online",
+  "name": "Sharepoint Online Connector",
+  "service_type": "sharepoint_online"
+}
+
+PUT _connector/my-spo-connector/_configuration
+{
+    "configuration": {
+        "client_id": {
+            "default_value": null,
+            "depends_on": [],
+            "display": "text",
+            "label": "Client ID",
+            "options": [],
+            "order": 3,
+            "required": true,
+            "sensitive": false,
+            "tooltip": null,
+            "type": "str",
+            "ui_restrictions": [],
+            "validations": [],
+            "value": null
+        },
+        "secret_value": {
+            "default_value": null,
+            "depends_on": [],
+            "display": "text",
+            "label": "Secret value",
+            "options": [],
+            "order": 4,
+            "required": true,
+            "sensitive": true,
+            "tooltip": null,
+            "type": "str",
+            "ui_restrictions": [],
+            "validations": [],
+            "value": null
+        }
+    }
 }
 --------------------------------------------------
 // TESTSETUP
 
 [source,console]
 --------------------------------------------------
-DELETE _connector/my-connector
+DELETE _connector/my-spo-connector
 --------------------------------------------------
 // TEARDOWN
 ////
 
+This example demonstrates how to register a `sharepoint_online` connector configuration schema. Note: The example does not cover all the necessary configuration fields for operating the Sharepoint Online connector.
+
 [source,console]
 ----
-PUT _connector/my-connector/_configuration
+PUT _connector/my-spo-connector/_configuration
 {
     "configuration": {
-        "service_account_credentials": {
+        "client_id": {
             "default_value": null,
             "depends_on": [],
-            "display": "textarea",
-            "label": "Google Drive service account JSON",
+            "display": "text",
+            "label": "Client ID",
             "options": [],
-            "order": 1,
+            "order": 3,
+            "required": true,
+            "sensitive": false,
+            "tooltip": null,
+            "type": "str",
+            "ui_restrictions": [],
+            "validations": [],
+            "value": null
+        },
+        "secret_value": {
+            "default_value": null,
+            "depends_on": [],
+            "display": "text",
+            "label": "Secret value",
+            "options": [],
+            "order": 4,
             "required": true,
             "sensitive": true,
-            "tooltip": "This connectors authenticates as a service account to synchronize content from Google Drive.",
+            "tooltip": null,
             "type": "str",
             "ui_restrictions": [],
             "validations": [],
-            "value": "...service account JSON..."
+            "value": null
         }
     }
 }
@@ -151,3 +207,43 @@ PUT _connector/my-connector/_configuration
     "result": "updated"
 }
 ----
+
+An example to update configuration values for the `sharepoint_online` connector:
+
+[source,console]
+----
+PUT _connector/my-spo-connector/_configuration
+{
+    "values": {
+        "client_id": "my-client-id",
+        "secret_value": "super-secret-value"
+    }
+}
+----
+
+[source,console-result]
+----
+{
+    "result": "updated"
+}
+----
+
+
+An example to update single configuration field of the `sharepoint_online` connector. In this case other configuration values won't change:
+
+[source,console]
+----
+PUT _connector/my-spo-connector/_configuration
+{
+    "values": {
+        "secret_value": "new-super-secret-value"
+    }
+}
+----
+
+[source,console-result]
+----
+{
+    "result": "updated"
+}
+----

docs/reference/connector/apis/update-connector-index-name-api.asciidoc

@@ -0,0 +1,85 @@
+[[update-connector-index-name-api]]
+=== Update connector index name API
+++++
+<titleabbrev>Update connector index name</titleabbrev>
+++++
+
+preview::[]
+
+Updates the `index_name` field of a connector, specifying the index where the data ingested by the connector is stored.
+
+[[update-connector-index-name-api-request]]
+==== {api-request-title}
+
+`PUT _connector/<connector_id>/_index_name`
+
+[[update-connector-index-name-api-prereq]]
+==== {api-prereq-title}
+
+* To sync data using connectors, it's essential to have the Elastic connectors service running.
+* The `connector_id` parameter should reference an existing connector.
+
+[[update-connector-index-name-api-path-params]]
+==== {api-path-parms-title}
+
+`<connector_id>`::
+(Required, string)
+
+[role="child_attributes"]
+[[update-connector-index-name-api-request-body]]
+==== {api-request-body-title}
+
+`index_name`::
+(Required, string) Index name where the connector ingests data. Each index name can be associated with at most one connector.
+
+
+[[update-connector-index-name-api-response-codes]]
+==== {api-response-codes-title}
+
+`200`::
+Connector `index_name` field was successfully updated.
+
+`400`::
+The `connector_id` was not provided or the request payload was malformed.
+
+`404` (Missing resources)::
+No connector matching `connector_id` could be found.
+
+[[update-connector-index-name-api-example]]
+==== {api-examples-title}
+
+The following example updates the `index_name` field for the connector with ID `my-connector`:
+
+////
+[source, console]
+--------------------------------------------------
+PUT _connector/my-connector
+{
+  "index_name": "search-google-drive",
+  "name": "My Connector",
+  "service_type": "google_drive"
+}
+--------------------------------------------------
+// TESTSETUP
+
+[source,console]
+--------------------------------------------------
+DELETE _connector/my-connector
+--------------------------------------------------
+// TEARDOWN
+////
+
+[source,console]
+----
+PUT _connector/my-connector/_index_name
+{
+    "index_name": "data-from-my-google-drive"
+}
+----
+
+[source,console-result]
+----
+{
+    "result": "updated"
+}
+----

docs/reference/connector/apis/update-connector-service-type-api.asciidoc

@@ -0,0 +1,87 @@
+[[update-connector-service-type-api]]
+=== Update connector service type API
+++++
+<titleabbrev>Update connector service type</titleabbrev>
+++++
+
+preview::[]
+
+Updates the `service_type` of a connector.
+
+[[update-connector-service-type-api-request]]
+==== {api-request-title}
+
+`PUT _connector/<connector_id>/_service_type`
+
+[[update-connector-service-type-api-prereq]]
+==== {api-prereq-title}
+
+* To sync data using connectors, it's essential to have the Elastic connectors service running.
+* The `connector_id` parameter should reference an existing connector.
+* The `service_type` must be a valid type as defined by the Connector framework.
+** When you change a configured connector's `service_type`, you'll also need to reset its configuration to ensure compatibility.
+
+[[update-connector-service-type-api-path-params]]
+==== {api-path-parms-title}
+
+`<connector_id>`::
+(Required, string)
+
+[role="child_attributes"]
+[[update-connector-service-type-api-request-body]]
+==== {api-request-body-title}
+
+`service_type`::
+(Required, string) A connector service type defined in the https://github.com/elastic/connectors/blob/main/connectors/config.py#L94[Connector framework].
+
+
+[[update-connector-service-type-api-response-codes]]
+==== {api-response-codes-title}
+
+`200`::
+Connector `service_type` field was successfully updated.
+
+`400`::
+The `connector_id` was not provided or the request payload was malformed.
+
+`404` (Missing resources)::
+No connector matching `connector_id` could be found.
+
+[[update-connector-service-type-api-example]]
+==== {api-examples-title}
+
+The following example updates the `service_type` of the connector with ID `my-connector`:
+
+////
+[source, console]
+--------------------------------------------------
+PUT _connector/my-connector
+{
+  "index_name": "search-google-drive",
+  "name": "My Connector",
+  "service_type": "google_drive"
+}
+--------------------------------------------------
+// TESTSETUP
+
+[source,console]
+--------------------------------------------------
+DELETE _connector/my-connector
+--------------------------------------------------
+// TEARDOWN
+////
+
+[source,console]
+----
+PUT _connector/my-connector/_service_type
+{
+    "service_type": "sharepoint_online"
+}
+----
+
+[source,console-result]
+----
+{
+    "result": "updated"
+}
+----

docs/reference/connector/apis/update-connector-status-api.asciidoc

@@ -0,0 +1,85 @@
+[[update-connector-status-api]]
+=== Update connector status API
+++++
+<titleabbrev>Update connector status</titleabbrev>
+++++
+
+preview::[]
+
+Updates the `status` of a connector.
+
+[[update-connector-status-api-request]]
+==== {api-request-title}
+
+`PUT _connector/<connector_id>/_status`
+
+[[update-connector-status-api-prereq]]
+==== {api-prereq-title}
+
+* To sync data using connectors, it's essential to have the Elastic connectors service running.
+* The `connector_id` parameter should reference an existing connector.
+* The change of `status` must be a valid status transition according to the https://github.com/elastic/connectors/blob/main/docs/CONNECTOR_PROTOCOL.md[Connector Protocol].
+
+[[update-connector-status-api-path-params]]
+==== {api-path-parms-title}
+
+`<connector_id>`::
+(Required, string)
+
+[role="child_attributes"]
+[[update-connector-status-api-request-body]]
+==== {api-request-body-title}
+
+`status`::
+(Required, string) A valid connector status string, defined in the Connector Framework.
+
+[[update-connector-status-api-response-codes]]
+==== {api-response-codes-title}
+
+`200`::
+Connector `status` field was successfully updated.
+
+`400`::
+The `connector_id` was not provided, the request payload was malformed, or the given status transition is not supported.
+
+`404` (Missing resources)::
+No connector matching `connector_id` could be found.
+
+[[update-connector-status-api-example]]
+==== {api-examples-title}
+
+The following example updates the `status` of the connector with ID `my-connector`:
+
+////
+[source, console]
+--------------------------------------------------
+PUT _connector/my-connector
+{
+  "index_name": "search-google-drive",
+  "name": "My Connector",
+  "service_type": "needs_configuration"
+}
+--------------------------------------------------
+// TESTSETUP
+
+[source,console]
+--------------------------------------------------
+DELETE _connector/my-connector
+--------------------------------------------------
+// TEARDOWN
+////
+
+[source,console]
+----
+PUT _connector/my-connector/_status
+{
+    "status": "needs_configuration"
+}
+----
+
+[source,console-result]
+----
+{
+    "result": "updated"
+}
+----

rest-api-spec/src/main/resources/rest-api-spec/api/connector.update_index_name.json

@@ -1,7 +1,7 @@
 {
   "connector.update_index_name": {
     "documentation": {
-      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/connector-apis.html",
+      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/update-connector-index-name-api.html",
       "description": "Updates the index name of the connector."
     },
     "stability": "experimental",

rest-api-spec/src/main/resources/rest-api-spec/api/connector.update_service_type.json

@@ -1,7 +1,7 @@
 {
   "connector.update_service_type": {
     "documentation": {
-      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/connector-apis.html",
+      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/update-connector-service-type-api.html",
       "description": "Updates the service type of the connector."
     },
     "stability": "experimental",

rest-api-spec/src/main/resources/rest-api-spec/api/connector.update_status.json

@@ -1,7 +1,7 @@
 {
   "connector.update_status": {
     "documentation": {
-      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/connector-apis.html",
+      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/update-connector-status-api.html",
       "description": "Updates the status of the connector."
     },
     "stability": "experimental",