Skip to content

Commit b7ee662

Browse files
Robert-StamRobert-Stam
authored
[CP-147] Added endpoints and samples to readme. (#99)
* [CP-147] Added endpoints and samples to readme. * Added that we support HTTP/2 as well. * Review remarks addressed * format * more format * more format * Use <> * Fixed anker
1 parent f3e0e55 commit b7ee662

1 file changed

Lines changed: 122 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 122 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,120 @@
11
# Qdrant Cloud API
22

3-
This repository contains the Protocol Buffer definitions for the Qdrant Cloud API, as well as its generated code.
3+
Welcome to the Qdrant Cloud API [repository](https://github.com/qdrant/qdrant-cloud-public-api)!
4+
5+
## Introduction
6+
7+
This repository hosts the Protocol Buffer (`.proto`) definitions that define the contract for interacting with Qdrant Cloud platform services.
8+
9+
The Qdrant Cloud API offers two main ways to interact:
10+
11+
* **gRPC:** For high-performance, type-safe communication, ideal for backend services and (newer) clients.
12+
* **REST/JSON:** A conventional HTTP/1.1 (and HTTP/2) based interface with JSON payloads, provided via gRPC Gateway for ease of use with tools.
13+
14+
This repository also contains generated client libraries (SDKs) for Go, Python, and TypeScript (found in the `gen/` directory) to help you get started quickly.
15+
16+
If you plan to contribute, please review the Protobuf guidelines to ensure our API remains consistent and user-friendly.
17+
18+
## API Endpoints
19+
20+
* **gRPC:** `grpc.cloud.qdrant.io:443`
21+
* **REST/JSON:** `https://api.cloud.qdrant.io`
22+
23+
Authentication is typically handled via API keys (so called management keys), which are passed in the `Authorization` header as an apikey (e.g., `Authorization: apikey <YOUR_MANAGEMENT_KEY>`).
24+
25+
## Interacting with the API
26+
27+
You can interact with the Qdrant Cloud API directly using tools like `grpcurl` (for gRPC) and `curl` (for REST/JSON), or by using the provided client libraries.
28+
29+
The API is used in the [TerraformProvider](https://registry.terraform.io/providers/qdrant/qdrant-cloud/latest) as well, so this can be used to interact as well.
30+
The sources for the TerraformProvider can be found [in Github here](https://github.com/qdrant/terraform-provider-qdrant-cloud).
31+
32+
### Using `grpcurl` (for gRPC)
33+
34+
`grpcurl` is a command-line tool that lets you interact with gRPC servers. It's great for exploring and testing APIs.
35+
36+
#### Example: List available services with `grpcurl`
37+
38+
```sh
39+
grpcurl grpc.cloud.qdrant.io:443 list
40+
```
41+
42+
#### Example: Describe a service (e.g., ClusterService)
43+
44+
```sh
45+
grpcurl grpc.cloud.qdrant.io:443 describe qdrant.cloud.cluster.v1.ClusterService
46+
```
47+
48+
#### Example: Call a method with gRPC (e.g., ListClusters on ClusterService)
49+
50+
```sh
51+
grpcurl -H "Authorization: apikey <YOUR_MANAGEMENT_KEY>" \
52+
-d '{"account_id": "<YOUR_ACCOUNT_ID>"}' \
53+
grpc.cloud.qdrant.io:443 \
54+
qdrant.cloud.cluster.v1.ClusterService/ListClusters
55+
```
56+
57+
*Note: Replace `<YOUR_MANAGEMENT_KEY>` with your actual management key and `<YOUR_ACCOUNT_ID>` with your account ID. The specific service and method names can be found in the `.proto` files under the `proto/` directory or by using `grpcurl list` and `grpcurl describe`.*
58+
59+
Assuming you have exported your management key in the environment variable `MANAGEMENT_KEY`, you can replace the first line with:
60+
61+
```sh
62+
grpcurl -H "Authorization: apikey ${MANAGEMENT_KEY}" \
63+
...
64+
```
65+
66+
### Using `curl` (for REST/JSON)
67+
68+
The REST/JSON API is available over HTTPS and uses standard HTTP methods.
69+
70+
#### Example: Call a method with REST/JSON (e.g., Listclusters on ClusterService)
71+
72+
```sh
73+
curl -X GET \
74+
-H "Authorization: apikey <YOUR_MANAGEMENT_KEY>" \
75+
"https://api.cloud.qdrant.io/api/cluster/v1/accounts/<YOUR_ACCOUNT_ID>/clusters"
76+
```
77+
78+
*Note: Replace `<YOUR_MANAGEMENT_KEY>` with your actual management key and `<YOUR_ACCOUNT_ID>` with your account ID. The exact REST path and HTTP method depend on the `google.api.http` annotations in the `.proto` files.*
79+
80+
You can typically infer these from the gRPC service and method names, or refer to the API documentation. Or check the output of grpcurl like:
81+
82+
```
83+
rpc CreateCluster ( .qdrant.cloud.cluster.v1.CreateClusterRequest ) returns ( .qdrant.cloud.cluster.v1.CreateClusterResponse ) {
84+
option (.google.api.http) = {
85+
post: "/api/cluster/v1/accounts/{cluster.account_id}/clusters",
86+
body: "*"
87+
};
88+
option (.qdrant.cloud.common.v1.permissions) = "write:clusters";
89+
}
90+
...
91+
```
92+
93+
Consider using `| jq` to format the output.
94+
95+
*For methods requiring a request body (e.g., POST, PUT), you would use the `-d` option with a JSON payload:*
96+
97+
```sh
98+
curl -X POST \
99+
-H "Authorization: apikey <YOUR_MANAGEMENT_KEY>" \
100+
-H "Content-Type: application/json" \
101+
-d '{"field1": "value1", "field2": "value2"}' \
102+
"https://api.cloud.qdrant.io/v2/your-service/your-resource"
103+
```
104+
105+
### Using Generated Client Libraries (SDKs)
106+
107+
The `gen/` directory in this repository contains pre-generated client libraries (SDKs) to help you integrate the Qdrant Cloud API into your applications. These libraries provide type-safe methods to call the gRPC services directly.
108+
109+
We currently provide support for:
110+
* **Go:** `gen/go/`
111+
* **Python:** `gen/python/`
112+
* **TypeScript:** `gen/ts/`
113+
114+
See [below](#using-generated-code) for more details.
115+
116+
117+
## Working with Protocol Buffer definitions
4118

5119
We use [Buf](https://buf.build/) to lint the schemas and to generate language bindings.
6120

@@ -12,8 +126,6 @@ This project leverages Make to automate common tasks. To view all available comm
12126
make help
13127
```
14128

15-
## Working with Protocol Buffer definitions
16-
17129
### Adding/updating proto files
18130

19131
The API schema definitions are located under the `proto/` directory. Whenever you add or modify a `.proto` file, make sure that you format and lint it accordingly. You can do that running:
@@ -50,6 +162,7 @@ import (
50162
- Make sure you are authorised to gcloud. `gcloud auth application-default login`
51163

52164
- Install the package:
165+
53166
``` sh
54167
# install auth tool
55168
uv tool install keyring --with keyrings.google-artifactregistry-auth --force
@@ -79,22 +192,28 @@ import (
79192
80193
- Make sure you are authorised to gcloud. `gcloud auth application-default login`
81194
- Create `.npmrc` file in the root of your project with the following content:
195+
82196
```text
83197
@qdrant:registry=https://us-npm.pkg.dev/qdrant-cloud/npm/
84198
//us-npm.pkg.dev/qdrant-cloud/npm/:always-auth=true
85199
```
200+
86201
- Add auth script to your package.json file:
202+
87203
```json
88204
"scripts": {
89205
...
90206
"artifactregistry-login": "npx --registry=https://registry.npmjs.org google-artifactregistry-auth"
91207
...
92208
},
93209
```
210+
94211
- Run the auth script:
212+
95213
```shell
96214
npm run artifactregistry-login
97215
```
216+
98217
- Install the package:
99218
``` sh
100219
npm install @qdrant/qdrant-cloud-public-api

0 commit comments

Comments
 (0)