From b12a6a709402250f4213f5e9bef1f7d255b6588c Mon Sep 17 00:00:00 2001 From: Theo Nam Truong Date: Mon, 11 Dec 2023 12:00:22 -0700 Subject: [PATCH] Low-level APIs (#211) - 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 | 28 ++++++--- api_generator/lib/action_generator.rb | 2 +- api_generator/lib/api_generator.rb | 20 +++++- .../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/json.md | 62 +++++++++++++++++++ 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/README.md | 14 +++++ samples/json.rb | 40 ++++++++++++ .../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, 834 insertions(+), 10 deletions(-) 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/json.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/README.md create mode 100644 samples/json.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 9eed888b4..3a31fea5e 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.get`, `http.post`, `http.patch`, `http.put`, `http.trace`, `http.head`, `http.options`, `http.connect`, and `http.delete` ([#211](https://github.com/opensearch-project/opensearch-ruby/pull/211)) +- Added a guide and a sample for `http` namespace ([#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..1eb22b96a 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) +- [Custom HTTP Requests](guides/json.md) ## Amazon OpenSearch Service diff --git a/api_generator/USER_GUIDE.md b/api_generator/USER_GUIDE.md index 9ca757ce5..7a39c8ed0 100644 --- a/api_generator/USER_GUIDE.md +++ b/api_generator/USER_GUIDE.md @@ -3,10 +3,10 @@ This API Generator generates API actions for the OpenSearch Ruby client based of --- ### Usage -This generator should be run everytime the OpenSearch API Specification is updated to propagate the changes to the Ruby client. For now, this must be done manually: +This generator should be run everytime the OpenSearch API specification is updated to propagate the changes to the Ruby client. For now, this must be done manually: - Create a new branch from `main` - Download the latest OpenSearch API Specification from [The API Spec Repo](https://github.com/opensearch-project/opensearch-api-specification/blob/main/OpenSearch.openapi.json) -- Run the generator with the API Spec downloaded previously (see below) +- Run the generator with the API spec downloaded previously (see below) - Run Rubocop with `-a` flag to remove redundant spacing from the generated code `rubocop -a` - Commit and create a PR to merge the updated API actions into `main`. @@ -22,27 +22,39 @@ require './lib/api_generator' generator = ApiGenerator.new('./OpenSearch.openapi.json') ``` -The `generate` method accepts the path to the root directory of the `opensearch-ruby` gem as a parameter. By default, it points to the parent directory of the folder containing the generator script. For example to generate all actions into the `tmp` directory: +### Generate Spec Methods: + +The `generate_spec_methods` method accepts the path to the root directory of the `opensearch-ruby` gem as a parameter. By default, it points to the parent directory of the folder containing the generator script. For example to generate all actions into the `tmp` directory: ```ruby -generator.generate('./tmp') +generator.generate_spec_methods('./tmp') ``` You can also target a specific API version by passing in the version number as a parameter. For example to generate all actions for version `1.0` into the `tmp` directory: ```ruby -generator.generate(version: '1.0') +generator.generate_spec_methods(version: '1.0') ``` The generator also support incremental generation. For example, to generate all actions of the `cat` namespace: ```ruby -generator.generate(namespace: 'cat') +generator.generate_spec_methods(namespace: 'cat') ``` To limit it to specific actions of a namespace: ```ruby -generator.generate(namespace: 'cat', actions: %w[aliases allocation]) +generator.generate_spec_methods(namespace: 'cat', actions: %w[aliases allocation]) ``` Note that the root namespace is presented by an empty string `''`. For example, to generate all actions of the root namespace for OS version 2.3: ```ruby -generator.generate(version: '2.3', namespace: '') +generator.generate_spec_methods(version: '2.3', namespace: '') ``` + +### Generate Static Methods: + +To generate static methods: + +```ruby +generator.generate_static_methods +``` + +The static methods are independent of the spec. A change in the OpenSearch API spec will not affect these methods. \ 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..b9e3a0f6c 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 @@ -22,11 +23,12 @@ def initialize(openapi_spec) @spec = Openapi3Parser.load_file(openapi_spec) end + # Generate API methods from the OpenSearch Specs. # @param [String] gem_folder location of the API Gem folder (default to the parent folder of the generator) # @param [String] version target OpenSearch version to generate like "2.5" or "3.0" # @param [String] namespace namespace to generate (Default to all namespaces. Use '' for root) # @param [Array] actions list of actions in the specified namespace to generate (Default to all actions) - def generate(gem_folder = '../', version: nil, namespace: nil, actions: nil) + def generate_spec_methods(gem_folder = '../', version: nil, namespace: nil, actions: nil) gem_folder = Pathname gem_folder namespaces = existing_namespaces(gem_folder) target_actions(version, namespace, actions).each do |action| @@ -37,6 +39,22 @@ def generate(gem_folder = '../', version: nil, namespace: nil, actions: nil) IndexGenerator.new(gem_folder.join('lib/opensearch'), namespaces).generate end + # Generate basic HTTP methods that are independent of the OpenSearch Specs. + # @param [String] gem_folder location of the API Gem folder (default to the parent folder of the generator) + def generate_static_methods(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/json.md b/guides/json.md new file mode 100644 index 000000000..f09cd4563 --- /dev/null +++ b/guides/json.md @@ -0,0 +1,62 @@ +# Making raw HTTP requests + +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 raw HTTP requests 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 to connect to a local OpenSearch cluster using default security credentials: + +```ruby +require 'opensearch-ruby' +client = OpenSearch::Client.new( + hosts: ['https://localhost:9200'], + user: 'admin', + password: 'admin', + transport_options: { ssl: { verify: false } } +) +``` + +## The http Namespace + +The `http` namespace provides a method of every HTTP verb (GET, POST, HEAD...). 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.http.get`: + +```ruby +puts client.http.get('_cat/indices') +``` + +Of course, you can also pass query-string parameters, headers, and a request body to the `http` methods. For example, the following block of code creates an index named `movies` 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.http.put('movies', body: body, params: params, headers: headers) +``` + +If you provide the http method with a string as body, it will be sent to the server as is. However, you can also provide them with a Ruby hash or an array of hashes, and the client will convert them to a JSON string or a newline-delimited JSON (NDJSON) string respectively. For example, to create two documents in the `books` index using the `bulk` endpoint: + +```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) +``` + +Let's clean up and delete the `movies` index: + +```ruby +client.http.delete('movies') +``` + +The `http` namespace includes the following methods: +- get +- put +- post +- delete +- head +- options +- patch +- trace +- connect 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/README.md b/samples/README.md new file mode 100644 index 000000000..15495a0b8 --- /dev/null +++ b/samples/README.md @@ -0,0 +1,14 @@ +# OpenSearch Ruby Samples + +Most samples can be run using OpenSearch installed locally with docker. + +``` +docker pull opensearchproject/opensearch:latest +docker run -d -p 9200:9200 -p 9600:9600 -e "discovery.type=single-node" opensearchproject/opensearch:latest +``` + +## Run Samples + +``` +bundle exec ruby json.rb +``` \ No newline at end of file diff --git a/samples/json.rb b/samples/json.rb new file mode 100644 index 000000000..8c32adbbf --- /dev/null +++ b/samples/json.rb @@ -0,0 +1,40 @@ +# 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( + hosts: ['https://localhost:9200'], + user: 'admin', + password: 'admin', + transport_options: { ssl: { verify: false } } +) + +# 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/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