Skip to content

Commit

Permalink
fix(clients): update README snippets and contributing guides (#3257)
Browse files Browse the repository at this point in the history
  • Loading branch information
@shortcuts
shortcuts authored Jun 26, 2024
1 parent b84d736 commit 47dd4bb
Show file tree
Hide file tree
Showing 12 changed files with 504 additions and 275 deletions.
74 changes: 55 additions & 19 deletions clients/algoliasearch-client-csharp/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <The version you want to install>
```

### 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
<PackageReference Include="Algolia.Search" Version=${versions.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(
"<YOUR_INDEX_NAME>",
new Dictionary<string, string> { { "objectID", "id" }, { "test", "val" } }
);

// Poll the task status to know when it has been indexed
await client.WaitForTaskAsync("<YOUR_INDEX_NAME>", response.TaskID);

// Fetch search results, with typo tolerance
var response = await client.SearchAsync<Object>(
new SearchMethodParams
{
Requests = new List<SearchQuery>
{
new SearchQuery(
new SearchForHits
{
IndexName = "<YOUR_INDEX_NAME>",
Query = "<YOUR_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).
45 changes: 38 additions & 7 deletions clients/algoliasearch-client-dart/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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: "<YOUR_INDEX_NAME>",
body: {
'objectID': "id",
'test': "val",
},
);
// Poll the task status to know when it has been indexed
await client.waitTask('<YOUR_INDEX_NAME>', response.taskID);
// Fetch search results, with typo tolerance
final response = await client.search(
searchMethodParams: SearchMethodParams(
requests: [
SearchForHits(
indexName: "<YOUR_INDEX_NAME>",
query: "<YOUR_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).
71 changes: 62 additions & 9 deletions clients/algoliasearch-client-go/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,20 +23,73 @@
<a href="https://alg.li/support" target="_blank">Support</a>
</p>

# 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
* Typed requests and responses
* 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(
"<YOUR_INDEX_NAME>", 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("<YOUR_INDEX_NAME>", 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("<YOUR_INDEX_NAME>").SetQuery("<YOUR_QUERY>").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).
104 changes: 33 additions & 71 deletions clients/algoliasearch-client-java/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
<dependency>
<groupId>com.algolia</groupId>
<artifactId>algoliasearch</artifactId>
<version>LATEST</version>
</dependency>
```
* **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);
<dependency>
<groupId>com.algolia</groupId>
<artifactId>algoliasearch</artifactId>
<version>4.0.0-beta.36</version>
</dependency>
```

### 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<Contact> records = Arrays.asList(contact);
List<BatchRequest> 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("<YOUR_INDEX_NAME>", 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("<YOUR_INDEX_NAME>", response.getTaskID());

## 📝 Examples
// Fetch search results, with typo tolerance
client.search(
new SearchMethodParams()
.setRequests(List.of(new SearchForHits().setIndexName("<YOUR_INDEX_NAME>").setQuery("<YOUR_QUERY>").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).
Loading

1 comment on commit 47dd4bb

@github-actions
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎉 Published on https://api-clients-automation.netlify.app as production
🚀 Deployed on https://667c228036568b562c630bdd--api-clients-automation.netlify.app

Please sign in to comment.