Add a "build" section, doc for SDKecosystem/openapi

6 files changed, 369 insertions, 0 deletions

diff --git a/doc/book/build/_index.md b/doc/book/build/_index.md
new file mode 100644
index 00000000..9bb17086
--- /dev/null
+++ b/doc/book/build/_index.md
@@ -0,0 +1,54 @@
++++
+title = "Build your own app"
+weight = 4
+sort_by = "weight"
+template = "documentation.html"
++++
+
+Garage has many API that you can rely on to build complex applications.
+In this section, we reference the existing SDKs and give some code examples.
+
+
+## ⚠️ DISCLAIMER
+
+**K2V AND ADMIN SDK ARE TECHNICAL PREVIEWS**. The following limitations apply:
+  - The API is not complete, some actions are possible only through the `garage` binary
+  - The underlying admin API is not yet stable nor complete, it can breaks at any time
+  - The generator configuration is currently tweaked, the library might break at any time due to a generator change
+  - Because the API and the library are not stable, none of them are published in a package manager (npm, pypi, etc.)
+  - This code has not been extensively tested, some things might not work (please report!)
+
+To have the best experience possible, please consider:
+  - Make sure that the version of the library you are using is pinned (`go.sum`, `package-lock.json`, `requirements.txt`).
+  - Before upgrading your Garage cluster, make sure that you can find a version of this SDK that works with your targeted version and that you are able to update your own code to work with this new version of the library.
+  - Join our Matrix channel at `#garage:deuxfleurs.fr`, say that you are interested by this SDK, and report any friction.
+  - If stability is critical, mirror this repository on your own infrastructure, regenerate the SDKs and upgrade them at your own pace.
+
+
+## About the APIs
+
+Code can interact with Garage through 3 different APIs: S3, K2V, and Admin.
+Each of them has a specific scope.
+
+### S3
+
+De-facto standard, introduced by Amazon, designed to store blobs of data.
+
+### K2V
+
+A simple database API similar to RiakKV or DynamoDB.
+Think a key value store with some additional operations.
+Its design is inspired by Distributed Hash Tables (DHT).
+
+More information:
+  - [In the reference manual](@/documentation/reference-manual/k2v.md)
+
+
+### Administration
+
+Garage operations can also be automated through a REST API.
+We are currently building this SDK for [Python](@/documentation/build/python.md#admin-api), [Javascript](@/documentation/build/javascript.md#administration) and [Golang](@/documentation/build/golang.md#administration).
+
+More information:
+  - [In the reference manual](@/documentation/reference-manual/admin-api.md)
+  - [Full specifiction](https://garagehq.deuxfleurs.fr/api/garage-admin-v0.html)
diff --git a/doc/book/build/golang.md b/doc/book/build/golang.md
new file mode 100644
index 00000000..a508260e
--- /dev/null
+++ b/doc/book/build/golang.md
@@ -0,0 +1,69 @@
++++
+title = "Golang"
+weight = 30
++++
+
+## S3
+
+*Coming soon*
+
+Some refs:
+  - Minio minio-go-sdk
+    - [Reference](https://docs.min.io/docs/golang-client-api-reference.html)
+
+  - Amazon aws-sdk-go-v2
+    - [Installation](https://aws.github.io/aws-sdk-go-v2/docs/getting-started/)
+    - [Reference](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3)
+    - [Example](https://aws.github.io/aws-sdk-go-v2/docs/code-examples/s3/putobject/)
+
+## K2V
+
+*Coming soon*
+
+## Administration
+
+Install the SDK with:
+
+```bash
+go get git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-golang
+```
+
+A short example:
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "os"
+    garage "git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-golang"
+)
+
+func main() {
+    // Set Host and other parameters
+    configuration := garage.NewConfiguration()
+    configuration.Host = "127.0.0.1:3903"
+
+
+    // We can now generate a client
+    client := garage.NewAPIClient(configuration)
+
+    // Authentication is handled through the context pattern
+    ctx := context.WithValue(context.Background(), garage.ContextAccessToken, "s3cr3t")
+
+    // Send a request
+    resp, r, err := client.NodesApi.GetNodes(ctx).Execute()
+    if err != nil {
+        fmt.Fprintf(os.Stderr, "Error when calling `NodesApi.GetNodes``: %v\n", err)
+        fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
+    }
+
+    // Process the response
+    fmt.Fprintf(os.Stdout, "Target hostname: %v\n", resp.KnownNodes[resp.Node].Hostname)
+}
+```
+
+See also:
+ - [generated doc](https://git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-golang)
+ - [examples](https://git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-generator/src/branch/main/example/golang)
diff --git a/doc/book/build/javascript.md b/doc/book/build/javascript.md
new file mode 100644
index 00000000..ff009ffe
--- /dev/null
+++ b/doc/book/build/javascript.md
@@ -0,0 +1,55 @@
++++
+title = "Javascript"
+weight = 10
++++
+
+## S3
+
+*Coming soon*.
+
+Some refs:
+  - Minio SDK
+    - [Reference](https://docs.min.io/docs/javascript-client-api-reference.html)
+
+  - Amazon aws-sdk-js
+    - [Installation](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/getting-started.html)
+    - [Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html)
+    - [Example](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/s3-example-creating-buckets.html)
+
+## K2V
+
+*Coming soon*
+
+## Administration
+
+Install the SDK with:
+
+```bash
+npm install --save git+https://git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-js.git
+```
+
+A short example:
+
+```javascript
+const garage = require('garage_administration_api_v0garage_v0_8_0');
+
+const api = new garage.ApiClient("http://127.0.0.1:3903/v0");
+api.authentications['bearerAuth'].accessToken = "s3cr3t";
+
+const [node, layout, key, bucket] = [
+  new garage.NodesApi(api),
+  new garage.LayoutApi(api),
+  new garage.KeyApi(api),
+  new garage.BucketApi(api),
+];
+
+node.getNodes().then((data) => {
+  console.log(`nodes: ${Object.values(data.knownNodes).map(n => n.hostname)}`)
+}, (error) => {
+  console.error(error);
+});
+```
+
+See also:
+ - [sdk repository](https://git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-js)
+ - [examples](https://git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-generator/src/branch/main/example/javascript)
diff --git a/doc/book/build/others.md b/doc/book/build/others.md
new file mode 100644
index 00000000..341e82d5
--- /dev/null
+++ b/doc/book/build/others.md
@@ -0,0 +1,49 @@
++++
+title = "Others"
+weight = 99
++++
+
+## S3
+
+If you are developping a new application, you may want to use Garage to store your user's media.
+
+The S3 API that Garage uses is a standard REST API, so as long as you can make HTTP requests,
+you can query it. You can check the [S3 REST API Reference](https://docs.aws.amazon.com/AmazonS3/latest/API/API_Operations_Amazon_Simple_Storage_Service.html) from Amazon to learn more.
+
+Developping your own wrapper around the REST API is time consuming and complicated.
+Instead, there are some libraries already avalaible.
+
+Some of them are maintained by Amazon, some by Minio, others by the community.
+
+### PHP
+
+  - Amazon aws-sdk-php
+    - [Installation](https://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/getting-started_installation.html)
+    - [Reference](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html)
+    - [Example](https://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/s3-examples-creating-buckets.html)
+
+### Java
+
+  - Minio SDK
+    - [Reference](https://docs.min.io/docs/java-client-api-reference.html)
+
+  - Amazon aws-sdk-java
+    - [Installation](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html)
+    - [Reference](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3Client.html)
+    - [Example](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/examples-s3-objects.html)
+
+### .NET
+
+  - Minio SDK
+    - [Reference](https://docs.min.io/docs/dotnet-client-api-reference.html)
+
+  - Amazon aws-dotnet-sdk
+
+### C++
+
+  - Amazon aws-cpp-sdk
+
+### Haskell
+
+  - Minio SDK
+    - [Reference](https://docs.min.io/docs/haskell-client-api-reference.html)
diff --git a/doc/book/build/python.md b/doc/book/build/python.md
new file mode 100644
index 00000000..19912e85
--- /dev/null
+++ b/doc/book/build/python.md
@@ -0,0 +1,95 @@
++++
+title = "Python"
+weight = 20
++++
+
+## S3
+
+*Coming soon*
+
+Some refs:
+  - Minio SDK
+    - [Reference](https://docs.min.io/docs/python-client-api-reference.html)
+
+  - Amazon boto3
+    - [Installation](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html)
+    - [Reference](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html)
+    - [Example](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/s3-uploading-files.html)
+
+## K2V
+
+*Coming soon*
+
+## Admin API
+
+You need at least Python 3.6, pip, and setuptools.
+Because the python package is in a subfolder, the command is a bit more complicated than usual:
+
+```bash
+pip3 install --user 'git+https://git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-python'
+```
+
+Now, let imagine you have a fresh Garage instance running on localhost, with the admin API configured on port 3903 with the bearer `s3cr3t`:
+
+```python
+import garage_admin_sdk
+from garage_admin_sdk.apis import *
+from garage_admin_sdk.models import *
+
+configuration = garage_admin_sdk.Configuration(
+  host = "http://localhost:3903/v0",
+  access_token = "s3cr3t"
+)
+
+# Init APIs
+api = garage_admin_sdk.ApiClient(configuration)
+nodes, layout, keys, buckets = NodesApi(api), LayoutApi(api), KeyApi(api), BucketApi(api)
+
+# Display some info on the node
+status = nodes.get_nodes()
+print(f"running garage {status.garage_version}, node_id {status.node}")
+
+# Change layout of this node
+current = layout.get_layout()
+layout.add_layout({
+  status.node: NodeClusterInfo(
+    zone = "dc1",
+    capacity = 1,
+    tags = [ "dev" ],
+  )
+})
+layout.apply_layout(LayoutVersion(
+  version = current.version + 1
+))
+
+# Create key, allow it to create buckets
+kinfo = keys.add_key(AddKeyRequest(name="openapi"))
+
+allow_create = UpdateKeyRequestAllow(create_bucket=True)
+keys.update_key(kinfo.access_key_id, UpdateKeyRequest(allow=allow_create))
+
+# Create a bucket, allow key, set quotas
+binfo = buckets.create_bucket(CreateBucketRequest(global_alias="documentation"))
+binfo = buckets.allow_bucket_key(AllowBucketKeyRequest(
+  bucket_id=binfo.id,
+  access_key_id=kinfo.access_key_id,
+  permissions=AllowBucketKeyRequestPermissions(read=True, write=True, owner=True),
+))
+binfo = buckets.update_bucket(binfo.id, UpdateBucketRequest(
+  quotas=UpdateBucketRequestQuotas(max_size=19029801,max_objects=1500)))
+
+# Display key
+print(f"""
+cluster ready
+key id is {kinfo.access_key_id}
+secret key is {kinfo.secret_access_key}
+bucket {binfo.global_aliases[0]} contains {binfo.objects}/{binfo.quotas.max_objects} objects
+""")
+```
+
+*This example is named `short.py` in the example folder. Other python examples are also available.*
+
+See also:
+ - [sdk repo](https://git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-python)
+ - [examples](https://git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-generator/src/branch/main/example/python)
+
diff --git a/doc/book/build/rust.md b/doc/book/build/rust.md
new file mode 100644
index 00000000..7101ba6e
--- /dev/null
+++ b/doc/book/build/rust.md
@@ -0,0 +1,47 @@
++++
+title = "Rust"
+weight = 40
++++
+
+## S3
+
+*Coming soon*
+
+Some refs:
+  - Amazon aws-rust-sdk
+    - [Github](https://github.com/awslabs/aws-sdk-rust)
+
+## K2V
+
+*Coming soon*
+
+Some refs: https://git.deuxfleurs.fr/Deuxfleurs/garage/src/branch/main/src/k2v-client
+
+```bash
+# all these values can be provided on the cli instead
+export AWS_ACCESS_KEY_ID=GK123456
+export AWS_SECRET_ACCESS_KEY=0123..789
+export AWS_REGION=garage
+export K2V_ENDPOINT=http://172.30.2.1:3903
+export K2V_BUCKET=my-bucket
+
+cargo run --features=cli -- read-range my-partition-key --all
+
+cargo run --features=cli -- insert my-partition-key my-sort-key --text "my string1"
+cargo run --features=cli -- insert my-partition-key my-sort-key --text "my string2"
+cargo run --features=cli -- insert my-partition-key my-sort-key2 --text "my string"
+
+cargo run --features=cli -- read-range my-partition-key --all
+
+causality=$(cargo run --features=cli -- read my-partition-key my-sort-key2 -b | head -n1)
+cargo run --features=cli -- delete my-partition-key my-sort-key2 -c $causality
+
+causality=$(cargo run --features=cli -- read my-partition-key my-sort-key -b | head -n1)
+cargo run --features=cli -- insert my-partition-key my-sort-key --text "my string3" -c $causality
+
+cargo run --features=cli -- read-range my-partition-key --all
+```
+
+## Admin API
+
+*Coming soon*