Add ML Connector APIs

CHANGELOG.md

@@ -42,6 +42,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added `node_failures` to `DELETE /_search/scroll` and `DELETE /_search/scroll/{scroll_id}` ([#749](https://github.com/opensearch-project/opensearch-api-specification/pull/749))
 - Added `POST /_plugins/_ml/_train/{algorithm_name}`, `_predict/{algorithm_name}/{model_id}`, and `_train_predict/{algorithm_name}` ([#755](https://github.com/opensearch-project/opensearch-api-specification/pull/755))
 - Added `PUT /_plugins/_ml/model_groups/{model_group_id}`, `GET /_plugins/_ml/model_groups/_search`, and `POST /_plugins/_ml/model_groups/_search` ([#760](https://github.com/opensearch-project/opensearch-api-specification/pull/760))
+- Added `GET /_plugins/_ml/connectors/{connector_id}`, `_search`, `POST /_plugins/_ml/connectors/_search`, and `PUT /_plugins/_ml/connectors/{connector_id}` ([#764](https://github.com/opensearch-project/opensearch-api-specification/pull/764))
 
 ### Removed
 - Removed unsupported `_common.mapping:SourceField`'s `mode` field and associated `_common.mapping:SourceFieldMode` enum ([#652](https://github.com/opensearch-project/opensearch-api-specification/pull/652))

spec/namespaces/ml.yaml

@@ -183,6 +183,28 @@ paths:
         '200':
           $ref: '#/components/responses/ml.create_connector@200'
   /_plugins/_ml/connectors/{connector_id}:
+    get:
+      operationId: ml.get_connector.0
+      x-operation-group: ml.get_connector
+      x-version-added: '2.11'
+      description: Retrieves a standalone connector.
+      parameters:
+        - $ref: '#/components/parameters/ml.get_connector::path.connector_id'
+      responses:
+        '200':
+          $ref: '#/components/responses/ml.get_connector@200'
+    put:
+      operationId: ml.update_connector.0
+      x-operation-group: ml.update_connector
+      x-version-added: '2.12'
+      description: Updates a standalone connector.
+      parameters:
+        - $ref: '#/components/parameters/ml.update_connector::path.connector_id'
+      requestBody:
+        $ref: '#/components/requestBodies/ml.update_connector'
+      responses:
+        '200':
+          $ref: '#/components/responses/ml.update_connector@200'
     delete:
       operationId: ml.delete_connector.0
       x-operation-group: ml.delete_connector
@@ -192,6 +214,27 @@ paths:
       responses:
         '200':
           $ref: '#/components/responses/ml.delete_connector@200'
+  /_plugins/_ml/connectors/_search:
+    get:
+      operationId: ml.search_connectors.0
+      x-operation-group: ml.search_connectors
+      x-version-added: '2.11'
+      description: Searches for standalone connectors.
+      requestBody:
+        $ref: '#/components/requestBodies/ml.search_connectors'
+      responses:
+        '200':
+          $ref: '#/components/responses/ml.search_connectors@200'
+    post:
+      operationId: ml.search_connectors.1
+      x-operation-group: ml.search_connectors
+      x-version-added: '2.11'
+      description: Searches for standalone connectors.
+      requestBody:
+        $ref: '#/components/requestBodies/ml.search_connectors'
+      responses:
+        '200':
+          $ref: '#/components/responses/ml.search_connectors@200'
   /_plugins/_ml/agents/_register:
     post:
       operationId: ml.register_agents.0
@@ -401,6 +444,9 @@ components:
                 type: integer
               protocol:
                 type: string
+                enum:
+                  - aws_sigv4
+                  - http
               credential:
                 $ref: '../schemas/ml._common.yaml#/components/schemas/Credential'
               parameters:
@@ -419,6 +465,61 @@ components:
               - parameters
               - protocol
               - version
+    ml.update_connector:
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              name:
+                $ref: '../schemas/_common.yaml#/components/schemas/Name'
+              description:
+                type: string
+                description: The connector description.
+              version:
+                $ref: '../schemas/_common.yaml#/components/schemas/VersionNumber'
+              protocol:
+                type: string
+                description: The connector protocol.
+                enum:
+                  - aws_sigv4
+                  - http
+              parameters:
+                $ref: '../schemas/ml._common.yaml#/components/schemas/Parameters'
+              credential:
+                $ref: '../schemas/ml._common.yaml#/components/schemas/Credential'
+              actions:
+                type: array
+                items:
+                  $ref: '../schemas/ml._common.yaml#/components/schemas/Action'
+              backend_roles:
+                type: array
+                items:
+                  type: string
+                description: The backend roles.
+              access_mode:
+                type: string
+                description: The model group access mode.
+                enum: [private, public, restricted]
+              parameters.skip_validating_missing_parameters:
+                type: boolean
+                description: Whether to skip validating missing parameters.
+    ml.search_connectors:
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              query:
+                $ref: '../schemas/ml._common.yaml#/components/schemas/Query'
+              size:
+                type: integer
+                description: The number of connectors to return.
+              sort:
+                type: array
+                items:
+                  type: string
+                description: The sort order.
     ml.register_agents:
       content:
         application/json:
@@ -548,11 +649,26 @@ components:
             properties:
               connector_id:
                 type: string
+    ml.get_connector@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/ml._common.yaml#/components/schemas/GetConnectorResponse'
+    ml.update_connector@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/_common.yaml#/components/schemas/WriteResponseBase'
     ml.delete_connector@200:
       content:
         application/json:
           schema:
             $ref: '../schemas/_common.yaml#/components/schemas/WriteResponseBase'
+    ml.search_connectors@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/ml._common.yaml#/components/schemas/SearchConnectorsResponse'
     ml.register_agents@200:
       content:
         application/json:
@@ -633,6 +749,18 @@ components:
       required: true
       schema:
         type: string
+    ml.get_connector::path.connector_id:
+      name: connector_id
+      in: path
+      required: true
+      schema:
+        type: string
+    ml.update_connector::path.connector_id:
+      name: connector_id
+      in: path
+      required: true
+      schema:
+        type: string
     ml.delete_connector::path.connector_id:
       name: connector_id
       in: path

spec/schemas/ml._common.yaml

@@ -191,6 +191,18 @@ components:
         latest_version:
           type: integer
           description: The latest version.
+        protocol:
+          type: string
+          description: The connector protocol.
+          enum:
+            - aws_sigv4
+            - http
+        parameters:
+          $ref: '#/components/schemas/Parameters'
+        actions:
+          type: array
+          items:
+            $ref: '#/components/schemas/Action'
     ModelConfig:
       type: object
       properties:
@@ -807,4 +819,36 @@ components:
       properties:
         content_type:
           type: string
-      additionalProperties: true
+      additionalProperties: true
+    GetConnectorResponse:
+      type: object
+      properties:
+        name:
+          $ref: '_common.yaml#/components/schemas/Name'
+        version:
+          $ref: '_common.yaml#/components/schemas/VersionString'
+        description:
+          type: string
+          description: The connector description.
+        protocol:
+          type: string
+          description: The connector protocol.
+          enum:
+            - aws_sigv4
+            - http
+        parameters:
+          $ref: '#/components/schemas/Parameters'
+        actions:
+          type: array
+          items:
+            $ref: '#/components/schemas/Action'
+        created_time:
+          type: integer
+          format: int64
+          description: The created time.
+        last_updated_time:
+          type: integer
+          format: int64
+          description: The last updated time.
+    SearchConnectorsResponse:
+      $ref: '#/components/schemas/SearchResponse'

tests/plugins/ml/ml/connectors.yaml

@@ -41,6 +41,13 @@ chapters:
       status: 200
     output:
       test_connector_id: payload.connector_id
+  - synopsis: Get connector.
+    path: /_plugins/_ml/connectors/{connector_id}
+    method: GET
+    parameters:
+      connector_id: ${create_connector.test_connector_id}
+    response:
+      status: 200
   - synopsis: Delete connector.
     path: /_plugins/_ml/connectors/{connector_id}
     method: DELETE

tests/plugins/ml/ml/connectors/search.yaml

@@ -0,0 +1,66 @@
+$schema: ../../../../../json_schemas/test_story.schema.yaml
+
+description: Test the search of connectors.
+version: '>= 2.11'
+prologues:
+  - path: /_plugins/_ml/connectors/_create
+    id: create_connector
+    method: POST
+    request:
+      payload:
+        name: OpenAI Chat Connector
+        description: The connector to public OpenAI model service for GPT 3.5
+        version: 1
+        protocol: http
+        parameters:
+          endpoint: api.openai.com
+          model: gpt-3.5-turbo
+        credential:
+          openAI_key: test_api_key
+        actions:
+          - action_type: predict
+            method: POST
+            url: https://api.openai.com/v1/chat/completions
+            headers:
+              Authorization: Bearer Key
+            request_body: '{ "model": "model", "messages": "messages" }'
+    output:
+      test_connector_id: payload.connector_id
+epilogues:
+  - path: /_plugins/_ml/connectors/{connector_id}
+    method: DELETE
+    status: [200, 404]
+    parameters:
+      connector_id: ${create_connector.test_connector_id}
+chapters:
+  - synopsis: Search connector.
+    path: /_plugins/_ml/connectors/_search
+    method: GET
+    request:
+      payload:
+        query:
+          match_all: {}
+        size: 1000
+    response:
+      status: 200
+      payload:
+        hits:
+          hits:
+            - _score: 1
+  - synopsis: Search connector with a connector ID.
+    path: /_plugins/_ml/connectors/_search
+    method: POST
+    request:
+      payload:
+        query:
+          bool:
+            must:
+              - terms:
+                  _id: 
+                    - ${create_connector.test_connector_id}
+    response:
+      status: 200
+      payload:
+        hits:
+          hits:
+            - _score: 1

tests/plugins/ml/ml/connectors/update.yaml

@@ -0,0 +1,45 @@
+$schema: ../../../../../json_schemas/test_story.schema.yaml
+
+description: Test updating a connector.
+version: '>= 2.12'
+prologues:
+  - path: /_plugins/_ml/connectors/_create
+    id: create_connector
+    method: POST
+    request:
+      payload:
+        name: OpenAI Chat Connector
+        description: The connector to public OpenAI model service for GPT 3.5
+        version: 1
+        protocol: http
+        parameters:
+          endpoint: api.openai.com
+          model: gpt-3.5-turbo
+        credential:
+          openAI_key: test_api_key
+        actions:
+          - action_type: predict
+            method: POST
+            url: https://api.openai.com/v1/chat/completions
+            headers:
+              Authorization: Bearer Key
+            request_body: '{ "model": "model", "messages": "messages" }'
+    output:
+      test_connector_id: payload.connector_id
+epilogues:
+  - path: /_plugins/_ml/connectors/{connector_id}
+    method: DELETE
+    status: [200, 404]
+    parameters:
+      connector_id: ${create_connector.test_connector_id}
+chapters:
+  - synopsis: Update connector.
+    path: /_plugins/_ml/connectors/{connector_id}
+    method: PUT
+    parameters:
+      connector_id: ${create_connector.test_connector_id}
+    request:
+      payload:
+        name: This is the updated name.
+    response:
+      status: 200