From 47dd4bb5ba6352d081bbca58ae12c67425b5cb25 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Vannicatte?= Date: Wed, 26 Jun 2024 15:49:11 +0200 Subject: [PATCH] fix(clients): update README snippets and contributing guides (#3257) --- clients/algoliasearch-client-csharp/README.md | 74 ++++++++--- clients/algoliasearch-client-dart/README.md | 45 +++++-- clients/algoliasearch-client-go/README.md | 71 +++++++++-- clients/algoliasearch-client-java/README.md | 104 +++++---------- .../algoliasearch-client-javascript/README.md | 39 +++--- clients/algoliasearch-client-kotlin/README.md | 2 +- clients/algoliasearch-client-php/README.md | 88 +++++++++++++ clients/algoliasearch-client-python/README.md | 71 +++++------ clients/algoliasearch-client-ruby/README.md | 8 +- clients/algoliasearch-client-scala/README.md | 57 +++++++-- clients/algoliasearch-client-swift/README.md | 119 +++++------------- templates/kotlin/README.mustache | 101 ++++++++++++--- 12 files changed, 504 insertions(+), 275 deletions(-) create mode 100644 clients/algoliasearch-client-php/README.md diff --git a/clients/algoliasearch-client-csharp/README.md b/clients/algoliasearch-client-csharp/README.md index 55d455d787..c9623733a5 100644 --- a/clients/algoliasearch-client-csharp/README.md +++ b/clients/algoliasearch-client-csharp/README.md @@ -32,42 +32,78 @@ * Retry strategy & Helpers. **Migration note for v7.x** -> In February 2024, we released v7 of our .NET client. If you are using version 6.x of the client, read the [migration guide to version 7.x](https://www.algolia.com/doc/api-client/getting-started/upgrade-guides/csharp/). -This version has been completely rewritten and is part of the [Api Automation initiative](https://github.com/algolia/api-clients-automation), meaning that models and routes are generated from the Algolia APIs specifications. - -This version introduces breaking changes. A document has been created to help you migrate from v6 to v7. You can find it [here](https://api-clients-automation.netlify.app/docs/clients/migration-guides/). +> In July 2024, we released v7 of our .NET client. If you are using version 6.x of the client, read the [migration guide to version 7.x](https://www.algolia.com/doc/api-client/getting-started/upgrade-guides/csharp/). **Migration note from v5.x to v6.x** -> + > In January 2019, we released v6 of our .NET client. If you are using version 5.x of the client, read the [migration guide to version 6.x](https://www.algolia.com/doc/api-client/getting-started/upgrade-guides/csharp/). Version 5.x will **no longer** be under active development. ## πŸ’‘ Getting Started -Install the library with the `.NET CLI`: +To get started, first install the Algolia.Search client. -```sh* -dotnet add package Algolia.Search -``` +You can get the last version of the client from [NuGet](https://www.nuget.org/packages/Algolia.Search/). -or with the `Nuget Package Manager Console`: +If you are using the .NET CLI, you can install the package using the following command: -```sh* -Install-Package Algolia.Search +```bash +dotnet add package Algolia.Search --version ``` -### Documentation, Guides & API Reference +Or directly in your .csproj file: -You will find all you need to get started in our API Client Automation [documentation](https://api-clients-automation.netlify.app/docs/clients/csharp/). +```csharp + +``` -For full documentation, visit the **[Algolia .NET API Client documentation](https://www.algolia.com/doc/api-client/getting-started/install/csharp/)**. +You can now import the Algolia API client in your project and play with it. + +```csharp +using Algolia.Search.Clients; +using Algolia.Search.Http; + +var client = new SearchClient(new SearchConfig("YOUR_APP_ID", "YOUR_API_KEY")); + +// Add a new record to your Algolia index +var response = await client.SaveObjectAsync( + "", + new Dictionary { { "objectID", "id" }, { "test", "val" } } +); + +// Poll the task status to know when it has been indexed +await client.WaitForTaskAsync("", response.TaskID); + +// Fetch search results, with typo tolerance +var response = await client.SearchAsync( + new SearchMethodParams + { + Requests = new List + { + new SearchQuery( + new SearchForHits + { + IndexName = "", + Query = "", + HitsPerPage = 50, + } + ) + }, + } +); +``` -#### ASP.NET -If you're using ASP.NET, checkout the [following tutorial](https://www.algolia.com/doc/api-client/getting-started/tutorials/asp.net/csharp/). +For full documentation, visit the **[Algolia CSharp API Client](https://www.algolia.com/doc/api-client/getting-started/install/csharp/)**. ## ❓ Troubleshooting -Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/csharp/) where you will find answers for the most common issues and gotchas with the client. + +Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/csharp/) where you will find answers for the most common issues and gotchas with the client. You can also open [a GitHub issue](https://github.com/algolia/api-clients-automation/issues/new?assignees=&labels=&projects=&template=Bug_report.md) + +## Contributing + +This repository hosts the code of the generated Algolia API client for CSharp, if you'd like to contribute, head over to the [main repository](https://github.com/algolia/api-clients-automation). You can also find contributing guides on [our documentation website](https://api-clients-automation.netlify.app/docs/contributing/introduction). ## πŸ“„ License -Algolia .NET API Client is an open-sourced software licensed under the [MIT license](LICENSE.md). + +The Algolia .NET API Client is an open-sourced software licensed under the [MIT license](LICENSE). diff --git a/clients/algoliasearch-client-dart/README.md b/clients/algoliasearch-client-dart/README.md index a0788deb96..14ac9a4889 100644 --- a/clients/algoliasearch-client-dart/README.md +++ b/clients/algoliasearch-client-dart/README.md @@ -63,18 +63,49 @@ flutter pub add algoliasearch ### Step 2: Import the Package -Now, you can import the `algoliasearch` package in your Dart code for all operations, including indexing, search, and personalization: +You can now import the Algolia API client in your project and play with it. ```dart -import 'package:algoliasearch/algoliasearch.dart'; +import 'package:algolia_client_search/algolia_client_search.dart'; +// Alternatively, you can import `algoliasearch_lite`, a **search-only** version of the library, if you do not need the full feature set: +// import 'package:algoliasearch/algoliasearch_lite.dart'; + +final client = SearchClient(appId: 'YOUR_APP_ID', apiKey: 'YOUR_API_KEY'); + +// Add a new record to your Algolia index +final response = await client.saveObject( + indexName: "", + body: { + 'objectID': "id", + 'test': "val", + }, +); + +// Poll the task status to know when it has been indexed +await client.waitTask('', response.taskID); + +// Fetch search results, with typo tolerance +final response = await client.search( + searchMethodParams: SearchMethodParams( + requests: [ + SearchForHits( + indexName: "", + query: "", + hitsPerPage: 50, + ), + ], + ), +); ``` -Alternatively, you can import `algoliasearch_lite`, a **search-only** version of the library, if you do not need the full feature set: +## ❓ Troubleshooting -```dart -import 'package:algoliasearch/algoliasearch_lite.dart'; -``` +Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/dart/) where you will find answers for the most common issues and gotchas with the client. You can also open [a GitHub issue](https://github.com/algolia/api-clients-automation/issues/new?assignees=&labels=&projects=&template=Bug_report.md) + +## Contributing + +This repository hosts the code of the generated Algolia API client for Dart, if you'd like to contribute, head over to the [main repository](https://github.com/algolia/api-clients-automation). You can also find contributing guides on [our documentation website](https://api-clients-automation.netlify.app/docs/contributing/introduction). ## πŸ“„ License -Algolia API Client is an open-sourced software licensed under the [MIT license](LICENSE). +The Algolia Dart API Client is an open-sourced software licensed under the [MIT license](LICENSE). diff --git a/clients/algoliasearch-client-go/README.md b/clients/algoliasearch-client-go/README.md index fb489c4946..a2942b61f8 100644 --- a/clients/algoliasearch-client-go/README.md +++ b/clients/algoliasearch-client-go/README.md @@ -23,13 +23,6 @@ Support

-# Pre-Release Notice - -This version of the client is currently in pre-release, which means that it is still undergoing development and testing. While we have made every effort to ensure that the software is functional and stable, there may still be bugs or issues that need to be addressed. - -If you prefer to use the stable version of the client, please use the [latest stable version](https://pkg.go.dev/github.com/algolia/algoliasearch-client-go/v3?tab=versions). - - ## ✨ Features * Support Go 1.19 and above @@ -37,6 +30,66 @@ If you prefer to use the stable version of the client, please use the [latest st * First-class support for user-defined structures * Injectable HTTP client -# Contributing to this repository +## πŸ’‘ Getting Started + +First, install the Algolia API Go Client via the go get command: + +```bash +go get github.com/algolia/algoliasearch-client-go/v4 +``` + +You can now import the Algolia API client in your project and play with it. + + +```go +import "github.com/algolia/algoliasearch-client-go/v4/algolia/search" + +client, err := search.NewClient("YOUR_APP_ID", "YOUR_API_KEY") + +// Add a new record to your Algolia index +response, err := client.SaveObject(client.NewApiSaveObjectRequest( + "", map[string]any{"objectID": "id", "test": "val"}, +)) +if err != nil { + // handle the eventual error + panic(err) +} + +// use the model directly +print(response) + +// Poll the task status to know when it has been indexed +taskResponse, err := searchClient.WaitForTask("", response.TaskID, nil, nil, nil) +if err != nil { + panic(err) +} + +// Fetch search results, with typo tolerance +response, err := client.Search(client.NewApiSearchRequest( + + search.NewEmptySearchMethodParams().SetRequests( + []search.SearchQuery{*search.SearchForHitsAsSearchQuery( + search.NewEmptySearchForHits().SetIndexName("").SetQuery("").SetHitsPerPage(50))}), +)) +if err != nil { + // handle the eventual error + panic(err) +} + +// use the model directly +print(response) +``` + +For full documentation, visit the **[Algolia Go API Client](https://www.algolia.com/doc/api-client/getting-started/install/go/)**. + +## ❓ Troubleshooting + +Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/go/) where you will find answers for the most common issues and gotchas with the client. You can also open [a GitHub issue](https://github.com/algolia/api-clients-automation/issues/new?assignees=&labels=&projects=&template=Bug_report.md) + +## Contributing + +This repository hosts the code of the generated Algolia API client for Go, if you'd like to contribute, head over to the [main repository](https://github.com/algolia/api-clients-automation). You can also find contributing guides on [our documentation website](https://api-clients-automation.netlify.app/docs/contributing/introduction). + +## πŸ“„ License -The Algolia API clients are automatically generated, you can find everything here https://github.com/algolia/api-clients-automation +The Algolia Go API Client is an open-sourced software licensed under the [MIT license](LICENSE). diff --git a/clients/algoliasearch-client-java/README.md b/clients/algoliasearch-client-java/README.md index 515cd03ced..9fb428033a 100644 --- a/clients/algoliasearch-client-java/README.md +++ b/clients/algoliasearch-client-java/README.md @@ -27,101 +27,63 @@ * Thread-safe clients * Typed requests and responses -**Migration note from v2.x to v3.x** +**Migration note from v3.x to v4.x** > -> In June 2019, we released v3 of our Java client. If you are using version 2.x of the client, read the [migration guide to version 3.x](https://www.algolia.com/doc/api-client/getting-started/upgrade-guides/java/). -Version 2.x will **no longer** be under active development. +> In July 2024, we released the v4 of our Java client. If you are using version 2.x or 3.x of the client, read the [migration guide to version 4.x](https://www.algolia.com/doc/api-client/getting-started/upgrade-guides/java/). +Version 3.x will **no longer** be under active development. ## πŸ’‘ Getting Started -### Install - -* **Maven**: add the following to your `pom.xml` file: - - ```xml - - com.algolia - algoliasearch - LATEST - - ``` -* **Gradle**: add the following to your `build.gradle` file: - ```groovy - implementation "com.algolia:algoliasearch:$version" - ``` - -### Initialize the client - -To start, you need to initialize the client. To do this, you need your **Application ID** and **API Key**. -You can find both on [your Algolia account](https://www.algolia.com/api-keys). - -```java -SearchClient client = new SearchClient("MY_APPLICATION_ID", "MY_API_KEY"); -``` - -If you need to customize the configuration of the client, use -`ClientOptions` when instantiating the Algolia `SearchClient` instance. +To get started, add the algoliasearch-client-java dependency to your project, either with [Maven](Maven): ```java -ClientOptions options = ClientOptions.builder().setLogLevel(LogLevel.BODY).build(); -SearchClient client = new SearchClient("MY_APPLICATION_ID", "MY_API_KEY", options); + + com.algolia + algoliasearch + 4.0.0-beta.36 + ``` -### Push data - -Without any prior configuration, you can start indexing contacts in the `contacts` index using the following code: +or [Gradle](https://gradle.org/): ```java -class Contact { - private String firstname; - private String lastname; - private int followers; - private String company; - private String objectID; - // Getters/setters ommitted +dependencies { + implementation 'com.algolia:algoliasearch:4.0.0-beta.36' } - -Contact contact = new Contact() - .setObjectID("one") - .setFirstname("Jimmie") - .setLastname("Barninger") - .setFollowers(93) - .setCompany("California Paint"); - -List records = Arrays.asList(contact); -List batch = records.stream() - .map(entry -> new BatchRequest().setAction(Action.ADD_OBJECT).setBody(entry)) - .toList(); -BatchResponse response = client.batch("contacts", new BatchWriteParams().setRequests(batch)); ``` -### Search - -You can now search for contacts by `firstname`, `lastname`, `company`, etc. (even with typos): +You can now import the Algolia API client in your project and play with it. ```java -SearchParams params = SearchParams.of(new SearchParamsObject().setQuery("jimmie")); +import com.algolia.api.SearchClient; +import com.algolia.model.search.*; -// Synchronous search -client.searchSingleIndex("contacts", params, Contact.class); +SearchClient client = new SearchClient("YOUR_APP_ID", "YOUR_API_KEY"); -// Asynchronous search -client.searchSingleIndexAsync("contacts", params, Contact.class); -``` +// Add a new record to your Algolia index +client.saveObject("", Map.of("objectID", "id", "test", "val")); -For full documentation, visit the [Algolia Java API Client's documentation](https://www.algolia.com/doc/api-client/getting-started/install/java/). +// Poll the task status to know when it has been indexed +client.waitForTask("", response.getTaskID()); -## πŸ“ Examples +// Fetch search results, with typo tolerance +client.search( + new SearchMethodParams() + .setRequests(List.of(new SearchForHits().setIndexName("").setQuery("").setHitsPerPage(50))), + Hit.class +); +``` -You can find code samples in the [Algolia's API Clients playground](https://github.com/algolia/api-clients-playground/tree/master/java/src/main/java). +For full documentation, visit the **[Algolia Java API Client](https://www.algolia.com/doc/api-client/getting-started/install/java/)**. ## ❓ Troubleshooting -Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/java/) where you will find answers for the most common issues and gotchas with the client. +Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/java/) where you will find answers for the most common issues and gotchas with the client. You can also open [a GitHub issue](https://github.com/algolia/api-clients-automation/issues/new?assignees=&labels=&projects=&template=Bug_report.md) -## Use the Dockerfile +## Contributing -If you want to contribute to this project without installing all its dependencies, you can use our Docker image. Please check our [dedicated guide](DOCKER_README.MD) to learn more. +This repository hosts the code of the generated Algolia API client for Java, if you'd like to contribute, head over to the [main repository](https://github.com/algolia/api-clients-automation). You can also find contributing guides on [our documentation website](https://api-clients-automation.netlify.app/docs/contributing/introduction). ## πŸ“„ License -Algolia Java API Client is an open-sourced software licensed under the [MIT license](LICENSE). + +The Algolia Java API Client is an open-sourced software licensed under the [MIT license](LICENSE). diff --git a/clients/algoliasearch-client-javascript/README.md b/clients/algoliasearch-client-javascript/README.md index e83acb4cac..929be352cd 100644 --- a/clients/algoliasearch-client-javascript/README.md +++ b/clients/algoliasearch-client-javascript/README.md @@ -36,7 +36,9 @@ ## πŸ’‘ Getting Started -First, install Algolia JavaScript API Client via your favorite package manager: +To get started, you first need to install algoliasearch (or any other available API client package). + +All of our clients comes with type definition, and are available for both browser and node environments. ```bash yarn add algoliasearch@beta @@ -44,35 +46,43 @@ yarn add algoliasearch@beta npm install algoliasearch@beta ``` -Or Without a package manager: +Or use a specific package: -Add the following JavaScript snippet to the `` of your website: +```bash +yarn add @algolia/client-search@beta +# or +npm install @algolia/client-search@beta +``` + +Without a package manager + +Add the following JavaScript snippet to the of your website: ```html ``` -Then, create objects on your index: +You can now import the Algolia API client in your project and play with it. ```js -import { algoliasearch } from 'algoliasearch'; +import { searchClient } from '@algolia/client-search'; -const client = algoliasearch('YourApplicationID', 'YourAdminAPIKey'); +const client = searchClient('YOUR_APP_ID', 'YOUR_API_KEY'); // Add a new record to your Algolia index -const saveResponse = await client.saveObject({ +const response = await client.saveObject({ indexName: '', body: { objectID: 'id', test: 'val' }, }); // use typed response -console.log(saveResponse); +console.log(response); // Poll the task status to know when it has been indexed -await client.waitForTask({ indexName: '', taskID: saveResponse.taskID }); +await client.waitForTask({ indexName: '', taskID: response.taskID }); // Fetch search results, with typo tolerance -const searchResponse = await client.search({ +const response = await client.search({ requests: [ { indexName: '', @@ -83,16 +93,15 @@ const searchResponse = await client.search({ }); // use typed response -console.log(searchResponse); +console.log(response); ``` -For the full documentation, visit the **[online documentation](https://api-clients-automation.netlify.app/docs/clients/usage)**. +For full documentation, visit the **[Algolia JavaScript API Client](https://www.algolia.com/doc/api-client/getting-started/install/javascript/)**. ## ❓ Troubleshooting -Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/javascript/) where you will find answers for the most common issues and gotchas with the client. +Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/javascript/) where you will find answers for the most common issues and gotchas with the client. You can also open [a GitHub issue](https://github.com/algolia/api-clients-automation/issues/new?assignees=&labels=&projects=&template=Bug_report.md) ## πŸ“„ License -Algolia JavaScript API Client is an open-sourced software licensed under the [MIT license](LICENSE.md). - +The Algolia JavaScript API Client is an open-sourced software licensed under the [MIT license](LICENSE). diff --git a/clients/algoliasearch-client-kotlin/README.md b/clients/algoliasearch-client-kotlin/README.md index d2b9414987..1737b500b5 100644 --- a/clients/algoliasearch-client-kotlin/README.md +++ b/clients/algoliasearch-client-kotlin/README.md @@ -67,4 +67,4 @@ If you want to contribute to this project without installing all its dependencie ## πŸ“„ License -Algolia Kotlin API Client is an open-sourced software licensed under the [MIT license](LICENSE). +The Algolia Kotlin API Client is an open-sourced software licensed under the [MIT license](LICENSE). diff --git a/clients/algoliasearch-client-php/README.md b/clients/algoliasearch-client-php/README.md new file mode 100644 index 0000000000..7ea4970b7c --- /dev/null +++ b/clients/algoliasearch-client-php/README.md @@ -0,0 +1,88 @@ +

+ + Algolia for PHP + + +

The perfect starting point to integrate Algolia within your PHP project

+ +

+ CircleCI + Total Downloads + Latest Version + License +

+

+ +

+ Documentation β€’ + Laravel β€’ + Symfony β€’ + Community Forum β€’ + Stack Overflow β€’ + Report a bug β€’ + FAQ β€’ + Support +

+ +## ✨ Features + +- Thin & minimal low-level HTTP client to interact with Algolia's API +- Supports php `^8.0`. + +## πŸ’‘ Getting Started + +First, install Algolia PHP API Client via the [composer](https://getcomposer.org/) package manager: + +```bash +composer require algolia/algoliasearch-client-php "^4.0@beta" +``` + +You can now import the Algolia API client in your project and play with it. + +```php +use Algolia\AlgoliaSearch\Api\SearchClient; + +$client = SearchClient::create('', ''); + +// Add a new record to your Algolia index +$response = $client->saveObject( + '', + ['objectID' => 'id', + 'test' => 'val', + ], +); + +// play with the response +var_dump($response); + +// Poll the task status to know when it has been indexed +$client->waitForTask('', $response['taskID']); + +// Fetch search results, with typo tolerance +$response = $client->search( + ['requests' => [ + ['indexName' => '', + 'query' => '', + 'hitsPerPage' => 50, + ], + ], + ], +); + +// play with the response +var_dump($response); +``` + +For full documentation, visit the **[Algolia PHP API Client](https://www.algolia.com/doc/api-client/getting-started/install/php/)**. + +## ❓ Troubleshooting + +Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/php/) where you will find answers for the most common issues and gotchas with the client. You can also open [a GitHub issue](https://github.com/algolia/api-clients-automation/issues/new?assignees=&labels=&projects=&template=Bug_report.md) + +## Contributing + +This repository hosts the code of the generated Algolia API client for PHP, if you'd like to contribute, head over to the [main repository](https://github.com/algolia/api-clients-automation). You can also find contributing guides on [our documentation website](https://api-clients-automation.netlify.app/docs/contributing/introduction). + +## πŸ“„ License + +The Algolia PHP API Client is an open-sourced software licensed under the [MIT license](LICENSE). diff --git a/clients/algoliasearch-client-python/README.md b/clients/algoliasearch-client-python/README.md index 74f77182d8..3deae47e7a 100644 --- a/clients/algoliasearch-client-python/README.md +++ b/clients/algoliasearch-client-python/README.md @@ -25,7 +25,7 @@ ## ✨ Features - Thin & minimal low-level HTTP client to interact with Algolia's API -- Supports Python from `3.8` to `3.12` +- Supports Python from `3.8` ## πŸ’‘ Getting Started @@ -35,60 +35,61 @@ First, install Algolia Python API Client via the [pip](https://pip.pypa.io/en/st pip install --upgrade 'algoliasearch>=4.0,<5.0' ``` -Now you can initialize any client with your Algolia credentials, for example the SearchClient: +You can now import the Algolia API client in your project and play with it. ```py from algoliasearch.search.client import SearchClient -client = SearchClient.create("YOUR_APP_ID", "YOUR_API_KEY") -``` - -Add new object to your index: +_client = SearchClient("YOUR_APP_ID", "YOUR_API_KEY") -```py -save_resp = await client.save_object(index_name="nvim", body={"description": "blazing fast"}) -``` - -Wait for the task to be processed on the Algolia side - -```py -await client.wait_for_task(index_name="nvim", task_id=save_resp.task_id) -``` - -Finally, you may begin searching a object using the `search` method: - -```py -# using a raw dict +# Add a new record to your Algolia index +response = await _client.save_object( + index_name="", + body={ + "objectID": "id", + "test": "val", + }, +) -search_resp = await client.search(search_method_params={"requests": [{"indexName": "nvim"}]}) +# use the class directly +print(response) -# using the given models +# print the JSON response +print(response.to_json()) -from algoliasearch.search.models.search_method_params import SearchMethodParams -from algoliasearch.search.models.search_for_hits import SearchForHits -from algoliasearch.search.models.search_query import SearchQuery +# Poll the task status to know when it has been indexed +await client.wait_for_task(index_name="", task_id=response.task_id) -search_resp = await client.search( - search_method_params=SearchMethodParams( - requests=[ - SearchQuery(SearchForHits(index_name="nvim")), +# Fetch search results, with typo tolerance +response = await _client.search( + search_method_params={ + "requests": [ + { + "indexName": "", + "query": "", + "hitsPerPage": 50, + }, ], - ), + }, ) -print(search_resp.to_json()) +# use the class directly +print(response) + +# print the JSON response +print(response.to_json()) ``` For full documentation, visit the **[Algolia Python API Client](https://www.algolia.com/doc/api-client/getting-started/install/python/)**. ## ❓ Troubleshooting -Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/python/) where you will find answers for the most common issues and gotchas with the client. +Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/python/) where you will find answers for the most common issues and gotchas with the client. You can also open [a GitHub issue](https://github.com/algolia/api-clients-automation/issues/new?assignees=&labels=&projects=&template=Bug_report.md) -## Use the Dockerfile +## Contributing -If you want to contribute to this project without installing all its dependencies, you can use our Docker image. Please check our [dedicated guide](DOCKER_README.MD) to learn more. +This repository hosts the code of the generated Algolia API client for Python, if you'd like to contribute, head over to the [main repository](https://github.com/algolia/api-clients-automation). You can also find contributing guides on [our documentation website](https://api-clients-automation.netlify.app/docs/contributing/introduction). ## πŸ“„ License -Algolia Python API Client is an open-sourced software licensed under the [MIT license](LICENSE). +The Algolia Python API Client is an open-sourced software licensed under the [MIT license](LICENSE). diff --git a/clients/algoliasearch-client-ruby/README.md b/clients/algoliasearch-client-ruby/README.md index c22e049418..556ef17713 100644 --- a/clients/algoliasearch-client-ruby/README.md +++ b/clients/algoliasearch-client-ruby/README.md @@ -51,12 +51,12 @@ For full documentation, visit the **[Algolia Ruby API Client](https://www.algoli ## ❓ Troubleshooting -Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/ruby/) where you will find answers for the most common issues and gotchas with the client. +Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/ruby/) where you will find answers for the most common issues and gotchas with the client. You can also open [a GitHub issue](https://github.com/algolia/api-clients-automation/issues/new?assignees=&labels=&projects=&template=Bug_report.md) -## Upgrade from V1 to V2 +## Contributing -If you were using the v1 and wish to update to v2, please follow our [Upgrade Guide](upgrade_guide.md) +This repository hosts the code of the generated Algolia API client for Ruby, if you'd like to contribute, head over to the [main repository](https://github.com/algolia/api-clients-automation). You can also find contributing guides on [our documentation website](https://api-clients-automation.netlify.app/docs/contributing/introduction). ## πŸ“„ License -Algolia Ruby API Client is an open-sourced software licensed under the [MIT license](LICENSE.md). +The Algolia Ruby API Client is an open-sourced software licensed under the [MIT license](LICENSE). diff --git a/clients/algoliasearch-client-scala/README.md b/clients/algoliasearch-client-scala/README.md index 96c1cd469b..346fa273aa 100644 --- a/clients/algoliasearch-client-scala/README.md +++ b/clients/algoliasearch-client-scala/README.md @@ -35,6 +35,7 @@ and you might also target a dead machine. You should change this TTL by setting the property `networkaddress.cache.ttl`. For example, to set the cache to 60 seconds: + ```scala java.security.Security.setProperty("networkaddress.cache.ttl", "60"); ``` @@ -42,9 +43,9 @@ java.security.Security.setProperty("networkaddress.cache.ttl", "60"); For debug purposes, you can enable debug logging on the API client. It's using [slf4j](https://www.slf4j.org) so it should be compatible with most java loggers. -#### Install +## πŸ’‘ Getting Started -With [Maven](https://maven.apache.org/), add the following dependency to your `pom.xml` file: +To get started, add the algoliasearch-client-scala dependency to your project, with [Maven](https://maven.apache.org/), add the following dependency to your `pom.xml` file: ```xml @@ -79,20 +80,52 @@ For snapshots, add the `sonatype` repository: resolvers += "Sonatype OSS Snapshots" at "https://oss.sonatype.org/content/repositories/snapshots" ``` -In 30 seconds, this quick start tutorial will show you how to index and search objects. +You can now import the Algolia API client in your project and play with it. -#### ⚑️ Getting Started - -To start, you need to initialize the client. To do this, you need your **Application ID** and **API Key**. -You can find both on [your Algolia account](https://www.algolia.com/api-keys). +```scala +import algoliasearch.api.SearchClient + +val client = SearchClient(appId = "YOUR_APP_ID", apiKey = "YOUR_API_KEY") + +// Add a new record to your Algolia index +val response = client.saveObject( + indexName = "", + body = JObject(List(JField("objectID", JString("id")), JField("test", JString("val")))) +) + +// Use the response +val value = Await.result(response, Duration(100, "sec")) + +// Poll the task status to know when it has been indexed +client.waitTask("", response.getTaskID()) + +// Fetch search results, with typo tolerance +val response = client.search( + searchMethodParams = SearchMethodParams( + requests = Seq( + SearchForHits( + indexName = "", + query = Some(""), + hitsPerPage = Some(50) + ) + ) + ) +) + +// Use the response +val value = Await.result(response, Duration(100, "sec")) +``` -For full documentation, -visit the **[Algolia Scala API Client](https://www.algolia.com/doc/api-client/getting-started/install/scala/)**. +For full documentation, visit the **[Algolia Scala API Client](https://www.algolia.com/doc/api-client/getting-started/install/scala/)**. ## ❓ Troubleshooting -Encountering an issue? Before reaching out to support, -we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/scala/) where you will find answers for the most common issues and gotchas with the client. +Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/scala/) where you will find answers for the most common issues and gotchas with the client. You can also open [a GitHub issue](https://github.com/algolia/api-clients-automation/issues/new?assignees=&labels=&projects=&template=Bug_report.md) + +## Contributing + +This repository hosts the code of the generated Algolia API client for Scala, if you'd like to contribute, head over to the [main repository](https://github.com/algolia/api-clients-automation). You can also find contributing guides on [our documentation website](https://api-clients-automation.netlify.app/docs/contributing/introduction). ## πŸ“„ License -Algolia Scala API Client is an open-sourced software licensed under the [MIT license](LICENSE). + +The Algolia Scala API Client is an open-sourced software licensed under the [MIT license](LICENSE). diff --git a/clients/algoliasearch-client-swift/README.md b/clients/algoliasearch-client-swift/README.md index 951fffaacd..c69785571a 100644 --- a/clients/algoliasearch-client-swift/README.md +++ b/clients/algoliasearch-client-swift/README.md @@ -47,7 +47,7 @@ - Detailed logging - Injectable HTTP client -## Install +## πŸ’‘ Getting Started ### Swift Package Manager @@ -62,21 +62,12 @@ If you're a framework author and use Swift API Client as a dependency, update yo let package = Package( // 9.0.0 ..< 10.0.0 dependencies: [ - .package(url: "https://github.com/algolia/algoliasearch-client-swift", from: "9.0.0-alpha.0") + .package(url: "https://github.com/algolia/algoliasearch-client-swift", from: "9.0.0-beta.6") ], // ... ) ``` -Import the Core package and the required client package to your source code files: - -```swift -#if canImport(Core) - import Core -#endif -import Search // or Ingestion, for example -``` - ### Cocoapods [CocoaPods](https://cocoapods.org/) is a dependency manager for Cocoa projects. @@ -112,85 +103,37 @@ github "algolia/algoliasearch-client-swift" ~> 9.0.0-alpha.0 If this is your first time using Carthage in the project, you'll need to go through some additional steps as explained [over at Carthage](https://github.com/Carthage/Carthage#adding-frameworks-to-an-application). +You can now import the Algolia API client in your project and play with it. -## πŸ’‘ Getting Started - -### Initialize the client - -To start, you need to initialize the client. To do this, you need your **Application ID** and **API Key**. -You can find both on [your Algolia account](https://www.algolia.com/api-keys). +> Import the Core package and the required client package to your source code files: ```swift -let client = SearchClient(applicationID: applicationID, apiKey: apiKey) -``` - -### Push data - -Without any prior configuration, you can start indexing contacts in the `contacts` index using the following code: - -```swift -struct Contact: Encodable { - let firstname: String - let lastname: String - let followers: Int - let company: String -} - -let contacts: [Contact] = [ - .init(firstname: "Jimmie", lastname: "Barninger", followers: 93, company: "California Paint"), - .init(firstname: "Warren", lastname: "Speach", followers: 42, company: "Norwalk Crmc") -] - -for contact in contacts { - let saveObjRes = try await client.saveObject(indexName: "contacts", body: contact) - _ = try await client.getTask(indexName: "contacts", taskID: saveObjRes.taskID) -} -``` - -### Search - -You can now search for contacts by `firstname`, `lastname`, `company`, etc. (even with typos): - -```swift -let searchParams = SearchParamsObject(query: "Jimmy") - -let res = try await client.searchSingleIndex(indexName: "contacts", searchParams: .searchParamsObject(searchParams)) - -dump(res.hits[0]) -``` - -### Configure +#if canImport(Core) + import Core +#endif +import Search -Settings can be customized to tune the search behavior. For example, you can add a custom sort by number of followers to the already great built-in relevance: +let client = try SearchClient(appID: "YOUR_APP_ID", apiKey: "YOUR_API_KEY") -```swift -let indexSettings = IndexSettings(customRanking: ["desc(followers)"]) -try await client.setSettings(indexName: "contacts", indexSettings: indexSettings) -``` - -You can also configure the list of attributes you want to index by order of importance (first = most important): +// Add a new record to your Algolia index +let response = try await client.saveObject( + indexName: "", + body: ["objectID": "id", "test": "val"] +) -**Note:** Since the engine is designed to suggest results as you type, you'll generally search by prefix. -In this case the order of attributes is very important to decide which hit is the best: +// Poll the task status to know when it has been indexed +try await client.waitForTask(with: response.taskID, in: "") -```swift -let indexSettings = IndexSettings(searchableAttributes: ["lastname", "firstname", "company"]) -try await client.setSettings(indexName: "contacts", indexSettings: indexSettings) +// Fetch search results, with typo tolerance +let response: SearchResponses = try await client + .search(searchMethodParams: SearchMethodParams(requests: [SearchQuery.searchForHits(SearchForHits( + query: "", + hitsPerPage: 50, + indexName: "" + ))])) ``` -For full documentation, visit the [Algolia's API Clients Automation documentation](https://api-clients-automation.netlify.app/docs/clients/introduction). - -## πŸ“ Examples - -You can find code samples in the [Algolia's API Clients Automation guides](https://api-clients-automation.netlify.app/docs/clients/guides/send-data-to-algolia). - -## Contributing to this repository - -The Algolia API clients are automatically generated, you can find everything here https://github.com/algolia/api-clients-automation - -## πŸ“„ License - -Algolia Swift API Client is an open-sourced software licensed under the [MIT license](LICENSE). +For full documentation, visit the **[Algolia Swift API Client](https://www.algolia.com/doc/api-client/getting-started/install/swift/)**. ## Notes @@ -212,8 +155,14 @@ You can use the old library with Swift by one of the following ways: - `pod 'AlgoliaSearch-Client-Swift', '~> 8.19'` - `pod 'AlgoliaSearch-Client-Swift', :git => 'https://github.com/algolia/algoliasearch-client-swift.git', :branch => 'swift-4'` -## Getting Help +## ❓ Troubleshooting + +Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/swift/) where you will find answers for the most common issues and gotchas with the client. You can also open [a GitHub issue](https://github.com/algolia/api-clients-automation/issues/new?assignees=&labels=&projects=&template=Bug_report.md) + +## Contributing + +This repository hosts the code of the generated Algolia API client for Swift, if you'd like to contribute, head over to the [main repository](https://github.com/algolia/api-clients-automation). You can also find contributing guides on [our documentation website](https://api-clients-automation.netlify.app/docs/contributing/introduction). + +## πŸ“„ License -- **Need help**? Ask a question to the [Algolia Community](https://discourse.algolia.com/) or on [Stack Overflow](http://stackoverflow.com/questions/tagged/algolia). -- **Encountering an issue?** Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/swift/) where you will find answers for the most common issues and gotchas with the client. -- **Found a bug?** You can open a [GitHub issue](https://github.com/algolia/algoliasearch-client-swift/issues). +The Algolia Swift API Client is an open-sourced software licensed under the [MIT license](LICENSE). diff --git a/templates/kotlin/README.mustache b/templates/kotlin/README.mustache index a39b062faa..318efb619b 100644 --- a/templates/kotlin/README.mustache +++ b/templates/kotlin/README.mustache @@ -34,19 +34,86 @@ ## πŸ’‘ Getting Started -Install the Kotlin client by adding the following dependency to your `gradle.build` file: - - ```gradle - repositories { - mavenCentral() - } - - dependencies { - implementation "com.algolia:algoliasearch-client-kotlin:{{packageVersion}}" - } - ``` -Also, choose and add to your dependencies one of [Ktor http client engines](https://ktor.io/docs/http-client-engines.html). -Alternatively, you can use [algoliasearch-client-kotlin-bom](/client-bom). +### JVM + +1. Install the Kotlin client by adding the following dependency to your gradle.build file: + +```kotlin +repositories { + mavenCentral() +} + +dependencies { + implementation "com.algolia:algoliasearch-client-kotlin:3.0.0-beta.31" +} +``` + +2. Choose and add to your dependencies one of [Ktor’s engines](https://ktor.io/docs/http-client-engines.html). + +### BOM + +Alternatively, you can use algoliasearch-client-kotlin-bom by adding the following dependency to your build.gradle file + +```kotlin +dependencies { + // import Kotlin API client BOM + implementation platform("com.algolia:algoliasearch-client-kotlin-bom:3.0.0-beta.31}") + + // define dependencies without versions + implementation 'com.algolia:algoliasearch-client-kotlin' + runtimeOnly 'io.ktor:ktor-client-okhttp' +} +``` + +### Multiplaform + +In multiplatform projects, add Algolia API client dependency to commonMain, and choose an [engine](https://ktor.io/docs/http-client-engines.html) for each target. + +You can now import the Algolia API client in your project and play with it. + +```kotlin +import com.algolia.client.api.SearchClient + +val client = SearchClient(appId = "YOUR_APP_ID", apiKey = "YOUR_API_KEY") + +// Add a new record to your Algolia index +var response = client.saveObject( + indexName = "", + body = buildJsonObject { + put( + "objectID", + JsonPrimitive("id"), + ) + put( + "test", + JsonPrimitive("val"), + ) + }, +) + +// Use the response +println(response) + +// Poll the task status to know when it has been indexed +client.waitTask("", response.taskID) + +// Fetch search results, with typo tolerance +var response = client.search( + searchMethodParams = SearchMethodParams( + requests = listOf( + SearchForHits( + indexName = "", + query = "", + hitsPerPage = 50, + ), + ), + ), +) + +// Use the response +println(response) +``` + For full documentation, visit the **[Algolia Kotlin API Client](https://www.algolia.com/doc/api-client/getting-started/install/kotlin/)**. ### Guides @@ -59,12 +126,12 @@ For full documentation, visit the **[Algolia Kotlin API Client](https://www.algo ## ❓ Troubleshooting -Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/kotlin/) where you will find answers for the most common issues and gotchas with the client. +Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/api-client/troubleshooting/faq/kotlin/) where you will find answers for the most common issues and gotchas with the client. You can also open [a GitHub issue](https://github.com/algolia/api-clients-automation/issues/new?assignees=&labels=&projects=&template=Bug_report.md) -## Use the Dockerfile +## Contributing -If you want to contribute to this project without installing all its dependencies, you can use our Docker image. Please check our [dedicated guide](DOCKER_README.md) to learn more. +This repository hosts the code of the generated Algolia API client for Kotlin, if you'd like to contribute, head over to the [main repository](https://github.com/algolia/api-clients-automation). You can also find contributing guides on [our documentation website](https://api-clients-automation.netlify.app/docs/contributing/introduction). ## πŸ“„ License -Algolia Kotlin API Client is an open-sourced software licensed under the [MIT license](LICENSE). \ No newline at end of file +The Algolia Kotlin API Client is an open-sourced software licensed under the [MIT license](LICENSE). \ No newline at end of file