From 93b3efb20aa3196745cbc3f435871b1e928b1be4 Mon Sep 17 00:00:00 2001 From: Theo Truong Date: Thu, 2 Nov 2023 14:58:55 -0600 Subject: [PATCH] Low-level APIs - Generator for low-level methods - Generated low-level methods - Guide for low-level methods - Samples for low-level methods Signed-off-by: Theo Truong --- CHANGELOG.md | 2 + USER_GUIDE.md | 1 + api_generator/USER_GUIDE.md | 5 + api_generator/lib/action_generator.rb | 2 +- api_generator/lib/api_generator.rb | 15 +++ .../lib/low_level_action_generator.rb | 27 ++++++ .../lib/low_level_base_action_generator.rb | 30 ++++++ .../templates/low_level_action.mustache | 22 +++++ .../templates/low_level_base_action.mustache | 21 +++++ guides/low_level_api.md | 93 +++++++++++++++++++ lib/opensearch/api.rb | 1 + lib/opensearch/api/actions/http/connect.rb | 28 ++++++ lib/opensearch/api/actions/http/delete.rb | 28 ++++++ lib/opensearch/api/actions/http/get.rb | 28 ++++++ lib/opensearch/api/actions/http/head.rb | 28 ++++++ lib/opensearch/api/actions/http/options.rb | 28 ++++++ lib/opensearch/api/actions/http/patch.rb | 28 ++++++ lib/opensearch/api/actions/http/post.rb | 28 ++++++ lib/opensearch/api/actions/http/put.rb | 28 ++++++ lib/opensearch/api/actions/http/request.rb | 27 ++++++ lib/opensearch/api/actions/http/trace.rb | 28 ++++++ lib/opensearch/api/namespace/http.rb | 30 ++++++ samples/low_level_api.http_namespace.rb | 35 +++++++ samples/low_level_api.perform_request.rb | 36 +++++++ .../api/actions/http/connect_spec.rb | 28 ++++++ .../api/actions/http/delete_spec.rb | 28 ++++++ spec/opensearch/api/actions/http/get_spec.rb | 28 ++++++ spec/opensearch/api/actions/http/head_spec.rb | 28 ++++++ .../api/actions/http/options_spec.rb | 28 ++++++ .../opensearch/api/actions/http/patch_spec.rb | 32 +++++++ spec/opensearch/api/actions/http/post_spec.rb | 28 ++++++ spec/opensearch/api/actions/http/put_spec.rb | 37 ++++++++ .../opensearch/api/actions/http/trace_spec.rb | 28 ++++++ 33 files changed, 863 insertions(+), 1 deletion(-) create mode 100644 api_generator/lib/low_level_action_generator.rb create mode 100644 api_generator/lib/low_level_base_action_generator.rb create mode 100644 api_generator/templates/low_level_action.mustache create mode 100644 api_generator/templates/low_level_base_action.mustache create mode 100644 guides/low_level_api.md create mode 100644 lib/opensearch/api/actions/http/connect.rb create mode 100644 lib/opensearch/api/actions/http/delete.rb create mode 100644 lib/opensearch/api/actions/http/get.rb create mode 100644 lib/opensearch/api/actions/http/head.rb create mode 100644 lib/opensearch/api/actions/http/options.rb create mode 100644 lib/opensearch/api/actions/http/patch.rb create mode 100644 lib/opensearch/api/actions/http/post.rb create mode 100644 lib/opensearch/api/actions/http/put.rb create mode 100644 lib/opensearch/api/actions/http/request.rb create mode 100644 lib/opensearch/api/actions/http/trace.rb create mode 100644 lib/opensearch/api/namespace/http.rb create mode 100644 samples/low_level_api.http_namespace.rb create mode 100644 samples/low_level_api.perform_request.rb create mode 100644 spec/opensearch/api/actions/http/connect_spec.rb create mode 100644 spec/opensearch/api/actions/http/delete_spec.rb create mode 100644 spec/opensearch/api/actions/http/get_spec.rb create mode 100644 spec/opensearch/api/actions/http/head_spec.rb create mode 100644 spec/opensearch/api/actions/http/options_spec.rb create mode 100644 spec/opensearch/api/actions/http/patch_spec.rb create mode 100644 spec/opensearch/api/actions/http/post_spec.rb create mode 100644 spec/opensearch/api/actions/http/put_spec.rb create mode 100644 spec/opensearch/api/actions/http/trace_spec.rb diff --git a/CHANGELOG.md b/CHANGELOG.md index 435d8bc4f..3869a0470 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,8 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) ## [Unreleased] ### Added +- Added `http` namespace with low-level APIs ([#211](https://github.com/opensearch-project/opensearch-ruby/pull/211)) +- Added guide and samples for lowl-level APIS ([#211](https://github.com/opensearch-project/opensearch-ruby/pull/211)) ### Changed ### Deprecated ### Removed diff --git a/USER_GUIDE.md b/USER_GUIDE.md index 476e8bf65..027342154 100644 --- a/USER_GUIDE.md +++ b/USER_GUIDE.md @@ -138,6 +138,7 @@ response = client.search index: index_name, body: search { - [Advanced Index Actions](guides/advanced_index_actions.md) - [Index Templates](guides/index_template.md) - [Transport Options](guides/transport_options.md) +- [Low Level API](guides/low_level_api.md) ## Amazon OpenSearch Service diff --git a/api_generator/USER_GUIDE.md b/api_generator/USER_GUIDE.md index 9ca757ce5..4d6b00202 100644 --- a/api_generator/USER_GUIDE.md +++ b/api_generator/USER_GUIDE.md @@ -46,3 +46,8 @@ Note that the root namespace is presented by an empty string `''`. For example, ```ruby generator.generate(version: '2.3', namespace: '') ``` + +Generate low-level API actions: +```ruby +generator.generate_low_level +``` \ No newline at end of file diff --git a/api_generator/lib/action_generator.rb b/api_generator/lib/action_generator.rb index 989083b02..66d8199ad 100644 --- a/api_generator/lib/action_generator.rb +++ b/api_generator/lib/action_generator.rb @@ -74,7 +74,7 @@ def http_verb end def required_args - @action.required_components.map { |arg| { arg: } } + @action.required_components.map { |arg| { arg: arg } } .tap { |args| args.last&.[]=('_blank_line', true) } end diff --git a/api_generator/lib/api_generator.rb b/api_generator/lib/api_generator.rb index 843cc64aa..4606eadc6 100644 --- a/api_generator/lib/api_generator.rb +++ b/api_generator/lib/api_generator.rb @@ -12,6 +12,7 @@ require_relative 'spec_generator' require_relative 'namespace_generator' require_relative 'index_generator' +require_relative 'low_level_action_generator' # Generate API endpoints for OpenSearch Ruby client class ApiGenerator @@ -37,6 +38,20 @@ def generate(gem_folder = '../', version: nil, namespace: nil, actions: nil) IndexGenerator.new(gem_folder.join('lib/opensearch'), namespaces).generate end + def generate_low_level(gem_folder = '../') + gem_folder = Pathname gem_folder + namespaces = existing_namespaces(gem_folder) + low_level_namespace = 'http' + + NamespaceGenerator.new(gem_folder.join('lib/opensearch/api/namespace'), low_level_namespace).generate(namespaces) + LowLevelBaseActionGenerator.new(gem_folder.join('lib/opensearch/api/actions'), low_level_namespace).generate + IndexGenerator.new(gem_folder.join('lib/opensearch'), namespaces).generate + + %w[head get post put patch delete options trace connect].each do |action| + LowLevelActionGenerator.new(gem_folder.join('lib/opensearch/api/actions'), low_level_namespace, action).generate + end + end + private def target_actions(version, namespace, actions) diff --git a/api_generator/lib/low_level_action_generator.rb b/api_generator/lib/low_level_action_generator.rb new file mode 100644 index 000000000..3a35b6509 --- /dev/null +++ b/api_generator/lib/low_level_action_generator.rb @@ -0,0 +1,27 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# frozen_string_literal: true + +require_relative 'low_level_base_action_generator' + +# Generate low-level API actions via Mustache +class LowLevelActionGenerator < LowLevelBaseActionGenerator + self.template_file = './templates/low_level_action.mustache' + + def initialize(output_folder, namespace, action) + super(output_folder, namespace) + @action = action + end + + def lower_cased + @action.downcase + end + + def upper_cased + @action.upcase + end +end diff --git a/api_generator/lib/low_level_base_action_generator.rb b/api_generator/lib/low_level_base_action_generator.rb new file mode 100644 index 000000000..fec0884ac --- /dev/null +++ b/api_generator/lib/low_level_base_action_generator.rb @@ -0,0 +1,30 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# frozen_string_literal: true + +require_relative 'base_generator' + +# Generate low-level API actions via Mustache +class LowLevelBaseActionGenerator < BaseGenerator + self.template_file = './templates/low_level_base_action.mustache' + + def initialize(output_folder, namespace) + super(output_folder) + @namespace = namespace + @action = 'request' + end + + def namespace_module + @namespace.camelize + end + + private + + def output_file + create_folder(*[@output_folder, @namespace].compact).join("#{@action}.rb") + end +end diff --git a/api_generator/templates/low_level_action.mustache b/api_generator/templates/low_level_action.mustache new file mode 100644 index 000000000..a05720b5e --- /dev/null +++ b/api_generator/templates/low_level_action.mustache @@ -0,0 +1,22 @@ +{{{license_header}}} +{{{generated_code_warning}}} + +# frozen_string_literal: true + +module OpenSearch + module API + module {{namespace_module}} + module Actions + # Make a customized {{upper_cased}} request. + # + # @option arguments [String] :url Relative path to the endpoint (e.g. 'cat/indices/books,movies') (*Required*) + # @option arguments [Hash] :params Querystring parameters to be appended to the path + # @option arguments [Hash] :headers Custom HTTP headers + # @option arguments [String | Hash | Array] :body The body of the request + def {{lower_cased}}(url, headers: {}, body: nil, params: {}) + request('{{upper_cased}}', url, headers: headers, body: body, params: params) + end + end + end + end +end diff --git a/api_generator/templates/low_level_base_action.mustache b/api_generator/templates/low_level_base_action.mustache new file mode 100644 index 000000000..8c1e10b9d --- /dev/null +++ b/api_generator/templates/low_level_base_action.mustache @@ -0,0 +1,21 @@ +{{{license_header}}} +{{{generated_code_warning}}} + +# frozen_string_literal: true + +module OpenSearch + module API + module {{namespace_module}} + module Actions + private + + def request(method, url, headers: {}, body: nil, params: {}) + body = OpenSearch::API::Utils.__bulkify(body) if body.is_a?(Array) + headers.merge!('Content-Type' => 'application/x-ndjson') if body.is_a?(Array) + + perform_request(method, url, params, body, headers).body + end + end + end + end +end diff --git a/guides/low_level_api.md b/guides/low_level_api.md new file mode 100644 index 000000000..5a8fe070f --- /dev/null +++ b/guides/low_level_api.md @@ -0,0 +1,93 @@ +# Low-level API + +The OpenSearch client implements many high-level REST DSLs that invoke OpenSearch APIs. However you may find yourself in a situation that requires you to invoke an API that is not supported by the client. In this case, you can use the low-level API to invoke any OpenSearch API. This guide shows you different ways to make custom API calls using the OpenSearch Ruby client. + +## Setup +First, create a client instance with the following code: + +```ruby +require 'opensearch-ruby' +client = OpenSearch::Client.new({ host: 'localhost' }) +``` + + +## The perform_request Method + +Normally, to get a summary of all indices in the cluster, you would use `client.cat.indices()`. However, you can achieve the same result using `client.perform_request`: + +```ruby +puts client.perform_request('GET', '_cat/indices').body +``` +Note that the `perform_request` method returns an `OpenSearch::Transport::Transport::Response` object. To get the response body, you need to call the `body` method. + +As you may have guessed, the `perform_request` method also accepts query-string parameters, headers, and a request body. For example, to create in index named `books` with 5 shards and 2 replicas, with explicit timeout of 30 seconds, and content-type of `application/json`: + +```ruby +body = { settings: { number_of_shards: 5, number_of_replicas: 2 } } +params = { timeout: '30s' } +headers = { 'Content-Type' => 'application/json' } + +client.perform_request('PUT', 'books', params, body, headers) +``` + +The `perform_request` method only accepts the request body as a Ruby hash or a JSON string. If you want to pass a different type of body, you need to pass it as a string and set the `Content-Type` header accordingly. Some OpenSearch APIs, like `bulk`, accept a newline-delimited JSON (NDJSON) string as a request body. The following code creates two documents in the `books` index using NDJSON through the `perform_request` method: + +```ruby +body = [{ index: { _index: "books", _id: 1 } }, + { title: "The Lion King", year: 1994 }, + { index: { _index: "books", _id: 2 } }, + { title: "Beauty and the Beast", year: 1991 }] +headers = { 'Content-Type' => 'application/x-ndjson' } + +client.perform_request('POST', '_bulk', {}, OpenSearch::API::Utils.__bulkify(body), headers) +``` + +## The http Namespace + +The `http` namespace provides a set of methods that wrap the `perform_request` method. For example, to get a summary of all indices in the cluster: + +```ruby +puts client.http.get('_cat/indices') +``` + +Note that the `http` methods return the response body directly, like other API methods. + +Of course, you can also pass query-string parameters, headers, and a request body to the `http` methods. For example, to create an index named `movies` similar to the `books` index we created previously: + +```ruby +body = { settings: { number_of_shards: 5, number_of_replicas: 2 } } +params = { timeout: '30s' } +headers = { 'Content-Type' => 'application/json' } + +client.http.put('movies', body: body, params: params, headers: headers) +``` + +Unlike the `perform_request` method, on top of accepting a Ruby Hash or JSON string as the body, the `http` methods also accept an array of hashes. When such an array is passed as the body, the `http` methods will automatically convert it to NDJSON, and add the appropriate `Content-Type` header. The following code is equivalent to the previous example: + +```ruby +body = [{ index: { _index: "books", _id: 1 } }, + { title: "The Lion King", year: 1994 }, + { index: { _index: "books", _id: 2 } }, + { title: "Beauty and the Beast", year: 1991 }] + +client.http.post('_bulk', body: body) +``` + +The `http` namespace includes the following methods: +- get +- put +- post +- delete +- head +- options +- patch +- trace +- connect + + +## Cleanup +To clean up the resources created in this guide, delete the `books`, and `movies` index: + +```ruby +client.indices.delete(index: [:books, :movies]) +``` diff --git a/lib/opensearch/api.rb b/lib/opensearch/api.rb index b0c09650e..fcd9c8826 100644 --- a/lib/opensearch/api.rb +++ b/lib/opensearch/api.rb @@ -79,6 +79,7 @@ def self.included(base) OpenSearch::API::Cluster, OpenSearch::API::DanglingIndices, OpenSearch::API::Features, + OpenSearch::API::Http, OpenSearch::API::Indices, OpenSearch::API::Ingest, OpenSearch::API::Nodes, diff --git a/lib/opensearch/api/actions/http/connect.rb b/lib/opensearch/api/actions/http/connect.rb new file mode 100644 index 000000000..89c0c95ad --- /dev/null +++ b/lib/opensearch/api/actions/http/connect.rb @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# This code was generated from OpenSearch API Spec. +# Update the code generation logic instead of modifying this file directly. + +# frozen_string_literal: true + +module OpenSearch + module API + module Http + module Actions + # Make a customized CONNECT request. + # + # @option arguments [String] :url Relative path to the endpoint (e.g. 'cat/indices/books,movies') (*Required*) + # @option arguments [Hash] :params Querystring parameters to be appended to the path + # @option arguments [Hash] :headers Custom HTTP headers + # @option arguments [String | Hash | Array] :body The body of the request + def connect(url, headers: {}, body: nil, params: {}) + request('CONNECT', url, headers: headers, body: body, params: params) + end + end + end + end +end diff --git a/lib/opensearch/api/actions/http/delete.rb b/lib/opensearch/api/actions/http/delete.rb new file mode 100644 index 000000000..ca9ba90f4 --- /dev/null +++ b/lib/opensearch/api/actions/http/delete.rb @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# This code was generated from OpenSearch API Spec. +# Update the code generation logic instead of modifying this file directly. + +# frozen_string_literal: true + +module OpenSearch + module API + module Http + module Actions + # Make a customized DELETE request. + # + # @option arguments [String] :url Relative path to the endpoint (e.g. 'cat/indices/books,movies') (*Required*) + # @option arguments [Hash] :params Querystring parameters to be appended to the path + # @option arguments [Hash] :headers Custom HTTP headers + # @option arguments [String | Hash | Array] :body The body of the request + def delete(url, headers: {}, body: nil, params: {}) + request('DELETE', url, headers: headers, body: body, params: params) + end + end + end + end +end diff --git a/lib/opensearch/api/actions/http/get.rb b/lib/opensearch/api/actions/http/get.rb new file mode 100644 index 000000000..d726dc024 --- /dev/null +++ b/lib/opensearch/api/actions/http/get.rb @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# This code was generated from OpenSearch API Spec. +# Update the code generation logic instead of modifying this file directly. + +# frozen_string_literal: true + +module OpenSearch + module API + module Http + module Actions + # Make a customized GET request. + # + # @option arguments [String] :url Relative path to the endpoint (e.g. 'cat/indices/books,movies') (*Required*) + # @option arguments [Hash] :params Querystring parameters to be appended to the path + # @option arguments [Hash] :headers Custom HTTP headers + # @option arguments [String | Hash | Array] :body The body of the request + def get(url, headers: {}, body: nil, params: {}) + request('GET', url, headers: headers, body: body, params: params) + end + end + end + end +end diff --git a/lib/opensearch/api/actions/http/head.rb b/lib/opensearch/api/actions/http/head.rb new file mode 100644 index 000000000..2cf76fd12 --- /dev/null +++ b/lib/opensearch/api/actions/http/head.rb @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# This code was generated from OpenSearch API Spec. +# Update the code generation logic instead of modifying this file directly. + +# frozen_string_literal: true + +module OpenSearch + module API + module Http + module Actions + # Make a customized HEAD request. + # + # @option arguments [String] :url Relative path to the endpoint (e.g. 'cat/indices/books,movies') (*Required*) + # @option arguments [Hash] :params Querystring parameters to be appended to the path + # @option arguments [Hash] :headers Custom HTTP headers + # @option arguments [String | Hash | Array] :body The body of the request + def head(url, headers: {}, body: nil, params: {}) + request('HEAD', url, headers: headers, body: body, params: params) + end + end + end + end +end diff --git a/lib/opensearch/api/actions/http/options.rb b/lib/opensearch/api/actions/http/options.rb new file mode 100644 index 000000000..03b963bfe --- /dev/null +++ b/lib/opensearch/api/actions/http/options.rb @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# This code was generated from OpenSearch API Spec. +# Update the code generation logic instead of modifying this file directly. + +# frozen_string_literal: true + +module OpenSearch + module API + module Http + module Actions + # Make a customized OPTIONS request. + # + # @option arguments [String] :url Relative path to the endpoint (e.g. 'cat/indices/books,movies') (*Required*) + # @option arguments [Hash] :params Querystring parameters to be appended to the path + # @option arguments [Hash] :headers Custom HTTP headers + # @option arguments [String | Hash | Array] :body The body of the request + def options(url, headers: {}, body: nil, params: {}) + request('OPTIONS', url, headers: headers, body: body, params: params) + end + end + end + end +end diff --git a/lib/opensearch/api/actions/http/patch.rb b/lib/opensearch/api/actions/http/patch.rb new file mode 100644 index 000000000..1d93d4eb1 --- /dev/null +++ b/lib/opensearch/api/actions/http/patch.rb @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# This code was generated from OpenSearch API Spec. +# Update the code generation logic instead of modifying this file directly. + +# frozen_string_literal: true + +module OpenSearch + module API + module Http + module Actions + # Make a customized PATCH request. + # + # @option arguments [String] :url Relative path to the endpoint (e.g. 'cat/indices/books,movies') (*Required*) + # @option arguments [Hash] :params Querystring parameters to be appended to the path + # @option arguments [Hash] :headers Custom HTTP headers + # @option arguments [String | Hash | Array] :body The body of the request + def patch(url, headers: {}, body: nil, params: {}) + request('PATCH', url, headers: headers, body: body, params: params) + end + end + end + end +end diff --git a/lib/opensearch/api/actions/http/post.rb b/lib/opensearch/api/actions/http/post.rb new file mode 100644 index 000000000..60fc0015b --- /dev/null +++ b/lib/opensearch/api/actions/http/post.rb @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# This code was generated from OpenSearch API Spec. +# Update the code generation logic instead of modifying this file directly. + +# frozen_string_literal: true + +module OpenSearch + module API + module Http + module Actions + # Make a customized POST request. + # + # @option arguments [String] :url Relative path to the endpoint (e.g. 'cat/indices/books,movies') (*Required*) + # @option arguments [Hash] :params Querystring parameters to be appended to the path + # @option arguments [Hash] :headers Custom HTTP headers + # @option arguments [String | Hash | Array] :body The body of the request + def post(url, headers: {}, body: nil, params: {}) + request('POST', url, headers: headers, body: body, params: params) + end + end + end + end +end diff --git a/lib/opensearch/api/actions/http/put.rb b/lib/opensearch/api/actions/http/put.rb new file mode 100644 index 000000000..f34346cdd --- /dev/null +++ b/lib/opensearch/api/actions/http/put.rb @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# This code was generated from OpenSearch API Spec. +# Update the code generation logic instead of modifying this file directly. + +# frozen_string_literal: true + +module OpenSearch + module API + module Http + module Actions + # Make a customized PUT request. + # + # @option arguments [String] :url Relative path to the endpoint (e.g. 'cat/indices/books,movies') (*Required*) + # @option arguments [Hash] :params Querystring parameters to be appended to the path + # @option arguments [Hash] :headers Custom HTTP headers + # @option arguments [String | Hash | Array] :body The body of the request + def put(url, headers: {}, body: nil, params: {}) + request('PUT', url, headers: headers, body: body, params: params) + end + end + end + end +end diff --git a/lib/opensearch/api/actions/http/request.rb b/lib/opensearch/api/actions/http/request.rb new file mode 100644 index 000000000..e60eef75a --- /dev/null +++ b/lib/opensearch/api/actions/http/request.rb @@ -0,0 +1,27 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# This code was generated from OpenSearch API Spec. +# Update the code generation logic instead of modifying this file directly. + +# frozen_string_literal: true + +module OpenSearch + module API + module Http + module Actions + private + + def request(method, url, headers: {}, body: nil, params: {}) + body = OpenSearch::API::Utils.__bulkify(body) if body.is_a?(Array) + headers.merge!('Content-Type' => 'application/x-ndjson') if body.is_a?(Array) + + perform_request(method, url, params, body, headers).body + end + end + end + end +end diff --git a/lib/opensearch/api/actions/http/trace.rb b/lib/opensearch/api/actions/http/trace.rb new file mode 100644 index 000000000..b2f665478 --- /dev/null +++ b/lib/opensearch/api/actions/http/trace.rb @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# This code was generated from OpenSearch API Spec. +# Update the code generation logic instead of modifying this file directly. + +# frozen_string_literal: true + +module OpenSearch + module API + module Http + module Actions + # Make a customized TRACE request. + # + # @option arguments [String] :url Relative path to the endpoint (e.g. 'cat/indices/books,movies') (*Required*) + # @option arguments [Hash] :params Querystring parameters to be appended to the path + # @option arguments [Hash] :headers Custom HTTP headers + # @option arguments [String | Hash | Array] :body The body of the request + def trace(url, headers: {}, body: nil, params: {}) + request('TRACE', url, headers: headers, body: body, params: params) + end + end + end + end +end diff --git a/lib/opensearch/api/namespace/http.rb b/lib/opensearch/api/namespace/http.rb new file mode 100644 index 000000000..3fd045bfc --- /dev/null +++ b/lib/opensearch/api/namespace/http.rb @@ -0,0 +1,30 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# This code was generated from OpenSearch API Spec. +# Update the code generation logic instead of modifying this file directly. + +# frozen_string_literal: true + +module OpenSearch + module API + module Http + module Actions; end + + # Client for the "http" namespace (includes the Http::Actions methods) + class HttpClient + include Http::Actions + include Common::Client + include Common::Client::Base + end + + # Proxy method for HttpClient, available in the receiving object + def http + @http ||= HttpClient.new(self) + end + end + end +end diff --git a/samples/low_level_api.http_namespace.rb b/samples/low_level_api.http_namespace.rb new file mode 100644 index 000000000..55fc649f3 --- /dev/null +++ b/samples/low_level_api.http_namespace.rb @@ -0,0 +1,35 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# frozen_string_literal: true + +require 'opensearch-ruby' +client = OpenSearch::Client.new({ host: 'localhost' }) + +# Perform a GET request using http namespace +# (Retrieve a summary of all indices) +puts client.http.get('_cat/indices') + +# Perform a PUT request with body, query-string params, and headers using http namespace +# (Create an index called 'books' with 5 shards and 2 replicas) +body = { settings: { number_of_shards: 5, number_of_replicas: 2 } } +params = { timeout: '30s' } +headers = { 'Content-Type' => 'application/json' } + +client.http.put('books', body: body, params: params, headers: headers) + +# Perform a POST request with new-line delimited JSON body using http namespace +# (Add two documents to the 'books' index via _bulk endpoint) +body = [{ index: { _index: 'books', _id: 1 } }, + { title: 'The Lion King', year: 1994 }, + { index: { _index: 'books', _id: 2 } }, + { title: 'Beauty and the Beast', year: 1991 }] + +puts client.http.post('_bulk', body: body) + +# Perform a DELETE request using http namespace +# (Delete the 'books' index) +client.http.delete('books') diff --git a/samples/low_level_api.perform_request.rb b/samples/low_level_api.perform_request.rb new file mode 100644 index 000000000..b8a8bf800 --- /dev/null +++ b/samples/low_level_api.perform_request.rb @@ -0,0 +1,36 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# frozen_string_literal: true + +require 'opensearch-ruby' +client = OpenSearch::Client.new({ host: 'localhost' }) + +# Perform a GET request using perform_request method +# (Retrieve a summary of all indices) +puts client.perform_request('GET', '_cat/indices').body + +# Perform a PUT request with body, query-string params, and headers using perform_request method +# (Create an index called 'books' with 5 shards and 2 replicas) +body = { settings: { number_of_shards: 5, number_of_replicas: 2 } } +params = { timeout: '30s' } +headers = { 'Content-Type' => 'application/json' } + +client.perform_request('PUT', 'books', params, body, headers) + +# Perform a POST request with new-line delimited JSON body using perform_request method +# (Add two documents to the 'books' index via _bulk endpoint) +body = [{ index: { _index: 'books', _id: 1 } }, + { title: 'The Lion King', year: 1994 }, + { index: { _index: 'books', _id: 2 } }, + { title: 'Beauty and the Beast', year: 1991 }] +headers = { 'Content-Type' => 'application/x-ndjson' } + +puts client.perform_request('POST', '_bulk', {}, OpenSearch::API::Utils.__bulkify(body), headers).body + +# Perform a DELETE request using perform_request method +# (Delete the 'books' index) +client.perform_request('DELETE', 'books') diff --git a/spec/opensearch/api/actions/http/connect_spec.rb b/spec/opensearch/api/actions/http/connect_spec.rb new file mode 100644 index 000000000..94fbfeb30 --- /dev/null +++ b/spec/opensearch/api/actions/http/connect_spec.rb @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# This code was generated from OpenSearch API Spec. +# Update the code generation logic instead of modifying this file directly. + +# frozen_string_literal: true + +require_relative '../../../../spec_helper' + +describe 'client.http#connect' do + let(:expected_args) do + [ + 'CONNECT', + 'some/api', + {}, + nil, + {} + ] + end + + it 'performs the request' do + expect(client_double.http.connect('some/api')).to eq({}) + end +end diff --git a/spec/opensearch/api/actions/http/delete_spec.rb b/spec/opensearch/api/actions/http/delete_spec.rb new file mode 100644 index 000000000..0f152a524 --- /dev/null +++ b/spec/opensearch/api/actions/http/delete_spec.rb @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# This code was generated from OpenSearch API Spec. +# Update the code generation logic instead of modifying this file directly. + +# frozen_string_literal: true + +require_relative '../../../../spec_helper' + +describe 'client.http#delete' do + let(:expected_args) do + [ + 'DELETE', + 'books', + {}, + nil, + { foo: :bar } + ] + end + + it 'performs the request' do + expect(client_double.http.delete('books', headers: { foo: :bar })).to eq({}) + end +end diff --git a/spec/opensearch/api/actions/http/get_spec.rb b/spec/opensearch/api/actions/http/get_spec.rb new file mode 100644 index 000000000..debbf5a5d --- /dev/null +++ b/spec/opensearch/api/actions/http/get_spec.rb @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# This code was generated from OpenSearch API Spec. +# Update the code generation logic instead of modifying this file directly. + +# frozen_string_literal: true + +require_relative '../../../../spec_helper' + +describe 'client.http#get' do + let(:expected_args) do + [ + 'GET', + '_cat/indices', + { v: true }, + nil, + {} + ] + end + + it 'performs the request' do + expect(client_double.http.get('_cat/indices', params: { v: true })).to eq({}) + end +end diff --git a/spec/opensearch/api/actions/http/head_spec.rb b/spec/opensearch/api/actions/http/head_spec.rb new file mode 100644 index 000000000..f545842a3 --- /dev/null +++ b/spec/opensearch/api/actions/http/head_spec.rb @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# This code was generated from OpenSearch API Spec. +# Update the code generation logic instead of modifying this file directly. + +# frozen_string_literal: true + +require_relative '../../../../spec_helper' + +describe 'client.http#head' do + let(:expected_args) do + [ + 'HEAD', + 'books', + {}, + nil, + {} + ] + end + + it 'performs the request' do + expect(client_double.http.head('books')).to eq({}) + end +end diff --git a/spec/opensearch/api/actions/http/options_spec.rb b/spec/opensearch/api/actions/http/options_spec.rb new file mode 100644 index 000000000..78f05fe57 --- /dev/null +++ b/spec/opensearch/api/actions/http/options_spec.rb @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# This code was generated from OpenSearch API Spec. +# Update the code generation logic instead of modifying this file directly. + +# frozen_string_literal: true + +require_relative '../../../../spec_helper' + +describe 'client.http#options' do + let(:expected_args) do + [ + 'OPTIONS', + 'some/api', + {}, + nil, + {} + ] + end + + it 'performs the request' do + expect(client_double.http.options('some/api')).to eq({}) + end +end diff --git a/spec/opensearch/api/actions/http/patch_spec.rb b/spec/opensearch/api/actions/http/patch_spec.rb new file mode 100644 index 000000000..3ab5f7ef0 --- /dev/null +++ b/spec/opensearch/api/actions/http/patch_spec.rb @@ -0,0 +1,32 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# This code was generated from OpenSearch API Spec. +# Update the code generation logic instead of modifying this file directly. + +# frozen_string_literal: true + +require_relative '../../../../spec_helper' + +describe 'client.http#patch' do + let(:expected_args) do + [ + 'PATCH', + 'books/1984', + {}, + body, + {} + ] + end + + let(:body) do + { wonderful: 'tonight' } + end + + it 'performs the request' do + expect(client_double.http.patch('books/1984', body: body)).to eq({}) + end +end diff --git a/spec/opensearch/api/actions/http/post_spec.rb b/spec/opensearch/api/actions/http/post_spec.rb new file mode 100644 index 000000000..0ba64c463 --- /dev/null +++ b/spec/opensearch/api/actions/http/post_spec.rb @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# This code was generated from OpenSearch API Spec. +# Update the code generation logic instead of modifying this file directly. + +# frozen_string_literal: true + +require_relative '../../../../spec_helper' + +describe 'client.http#post' do + let(:expected_args) do + [ + 'POST', + 'books/_close', + {}, + nil, + {} + ] + end + + it 'performs the request' do + expect(client_double.http.post('books/_close')).to eq({}) + end +end diff --git a/spec/opensearch/api/actions/http/put_spec.rb b/spec/opensearch/api/actions/http/put_spec.rb new file mode 100644 index 000000000..21e4ecb47 --- /dev/null +++ b/spec/opensearch/api/actions/http/put_spec.rb @@ -0,0 +1,37 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# This code was generated from OpenSearch API Spec. +# Update the code generation logic instead of modifying this file directly. + +# frozen_string_literal: true + +require_relative '../../../../spec_helper' + +describe 'client.http#put' do + let(:expected_args) do + [ + 'PUT', + 'books', + {}, + body, + {} + ] + end + + let(:body) do + { + settings: { + number_of_shards: 3, + number_of_replicas: 2 + } + } + end + + it 'performs the request' do + expect(client_double.http.put('books', body: body)).to eq({}) + end +end diff --git a/spec/opensearch/api/actions/http/trace_spec.rb b/spec/opensearch/api/actions/http/trace_spec.rb new file mode 100644 index 000000000..aa58b7bf4 --- /dev/null +++ b/spec/opensearch/api/actions/http/trace_spec.rb @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: Apache-2.0 +# +# The OpenSearch Contributors require contributions made to +# this file be licensed under the Apache-2.0 license or a +# compatible open source license. + +# This code was generated from OpenSearch API Spec. +# Update the code generation logic instead of modifying this file directly. + +# frozen_string_literal: true + +require_relative '../../../../spec_helper' + +describe 'client.http#trace' do + let(:expected_args) do + [ + 'TRACE', + 'some/api', + {}, + nil, + {} + ] + end + + it 'performs the request' do + expect(client_double.http.trace('some/api')).to eq({}) + end +end