From 4296648576ee0478fba9e3f639dff8b61eb7bc51 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Thu, 9 Jan 2025 16:16:45 -0500 Subject: [PATCH] Doc review Signed-off-by: Fanit Kolchina --- ...22-Introducing-OpenSearch-JS-Client-3.0.md | 38 +++++++++++-------- 1 file changed, 22 insertions(+), 16 deletions(-) diff --git a/_posts/2025-01-22-Introducing-OpenSearch-JS-Client-3.0.md b/_posts/2025-01-22-Introducing-OpenSearch-JS-Client-3.0.md index 507887e52..adbb9060e 100644 --- a/_posts/2025-01-22-Introducing-OpenSearch-JS-Client-3.0.md +++ b/_posts/2025-01-22-Introducing-OpenSearch-JS-Client-3.0.md @@ -1,9 +1,10 @@ --- layout: post -title: "Introducing OpenSearch JS Client 3.0" +title: "Introducing OpenSearch JavaScript client 3.0" authors: - theotr -date: 2025-01-22 + - kolchfa +date: 2025-01-09 categories: - release meta_keywords: javascript, typescript, client, api, opensearch, release, codegen, api generator @@ -12,29 +13,34 @@ has_math: false has_science_table: false --- -We are excited to announce the release of OpenSearch JS Client 3.0.0. Through an [API generator](https://github.com/opensearch-project/opensearch-js/tree/main/api_generator), the client has received a major overhaul for better readability, consistency, and most importantly a more complete and accurate interface to interact with OpenSearch clusters. +We're excited to announce the release of OpenSearch JavaScript client 3.0.0. This version introduces significant improvements, including enhanced readability, consistency, and a more accurate interface for interacting with OpenSearch clusters. -## Automatically Updated API Functions: +The new [API generator](https://github.com/opensearch-project/opensearch-js/tree/main/api_generator) enables frequent and accurate updates to the client, ensuring it reflects the latest changes in OpenSearch. -Right off the bat, version 3.0.0 comes loaded with over a hundred new API functions compared to the previous 2.13.0 version, all generated from the [OpenSearch API specification](https://github.com/opensearch-project/opensearch-api-specification) which currently covers about 60% of the OpenSearch API. All existing API functions have also been updated to match the latest spec. We also include a GitHub workflow that automatically updates the client every week, ensuring that the client is always up-to-date with the latest OpenSearch API. That means you don't have to wait long to try new OpenSearch features through this client. +## Improved API coverage using automated updates -For client maintainers, this means less tedious work to keep the client up-to-date with the spec. We now can focus on improving the client's performance, stability, adding new features, and filling in the missing APIs by [adding them to the API specification](https://github.com/opensearch-project/opensearch-api-specification?tab=readme-ov-file#welcome). This also results in fewer issues related to outdated API functions, reducing headaches for both maintainers and users. +Version 3.0.0 introduces over 100 new API functions compared to version 2.13.0, all generated from the [OpenSearch API specification](https://github.com/opensearch-project/opensearch-api-specification), which currently covers about 60% of the OpenSearch API. All existing API functions have been updated to align with the latest API spec. -## TypeScript support: +To keep things current, we've added a GitHub workflow that automatically updates the client every week, ensuring that the client is always up-to-date with the latest OpenSearch API. This means that you always have access to the latest OpenSearch features through the client without delay. -Previous versions of the client came with an incomplete and outdated set of request and response types that were written by hand. This issue has been resolved with 3.0.0 as these handwritten types have been replaced with types generated from the OpenSearch API specification. The new type definitions are written in a way that makes it a lot easier for IDEs and AI/ML assistants to provide autocomplete and type checking. This greatly improves the developer experience for TypeScript users: faster development and fewer bugs. +For the client repository maintainers, this automation reduces the manual effort required to sync the client with the API spec. It allows us to focus on improving the client's performance, stability, and functionality while addressing API function gaps by [adding the missing APIs to the API specification](https://github.com/opensearch-project/opensearch-api-specification?tab=readme-ov-file#welcome). With the new API generator, you'll encounter fewer issues related to outdated API functions, creating a smoother experience whether you're a maintainer or a user. -## Removing Support for Outdated Features: +## Enhanced TypeScript support -A major update is also an opportunity to remove outdated features that are no longer necessary or have been replaced by better alternatives: +In previous versions, the client relied on incomplete and outdated types for requests and responses, which were manually written. Version 3.0.0 resolves this problem by generating types directly from the OpenSearch API specification. -* The client no longer allows overriding the HTTP method for API functions. In previous versions, some API functions let you pass method as a parameter to the API functions to override the default HTTP method. Now, method will be considered a querystring param, and using it will likely result in an error. If you need to send a custom request, you should use the client.http namespace. -* The client no longer supports camelCase parameters. Every API function now only accepts parameters matching the OpenSearch API Spec, which are also what the OpenSearch server expects. -* Support of Node.js 10 and 12 has been dropped. The client now requires Node.js 14 or higher. We strongly encourage users to upgrade to the latest LTS version of Node.js. +These new type definitions make it easier for your IDE or AI coding assistants to provide accurate autocomplete suggestions and perform type checks. If you use TypeScript, you'll notice faster development and fewer bugs, significantly improving your experience. -As with many major upgrades, the above-mentioned changes and the new comprehensive, precise and stricter typing system introduce some unavoidable breaking changes. For a complete list of changes and deprecations, please refer to the [upgrading guide](https://github.com/opensearch-project/opensearch-js/blob/main/UPGRADING.md). +## Removing support for outdated features +This major update also removes features that are no longer needed or have been replaced by better alternatives: ---- +- **No more HTTP method overrides:** Previously, some API functions allowed you to override the HTTP method using a `method` parameter. Now, `method` is treated as a query string parameter and using it may cause errors. To send custom requests, use the `client.http` namespace. +- **No camelCase parameters:** API functions now only accept parameters matching the OpenSearch API specification. These parameters align with what the OpenSearch server expects. +- **Dropped support for older Node.js versions:** The client now requires Node.js 14 or later. If you're still using Node.js 10 or 12, we recommend upgrading to the latest LTS version. + +As with any major update, these updates, along with the new typing system, may introduce breaking changes. For a detailed list of changes and deprecations, see the [UPGRADING guide](https://github.com/opensearch-project/opensearch-js/blob/main/UPGRADING.md). + +## Share your feedback -We hope you enjoy the new OpenSearch JS Client 3.0. We are excited to see what you build with it. If you have any questions or feedback, please don't hesitate to open an issue on the [GitHub repository](https://github.com/opensearch-project/opensearch-js). We are always looking to improve the client and make it easier for you to interact with OpenSearch clusters. \ No newline at end of file +We're excited to see the applications you build using the new OpenSearch JavaScript client 3.0.0. If you have questions or feedback, feel free to open an issue in the [JavaScript client GitHub repository](https://github.com/opensearch-project/opensearch-js). Your input helps us improve the client and make it easier for you to interact with OpenSearch clusters. \ No newline at end of file