From 6a435af04edb774b3b5f7d2619779f3e79275839 Mon Sep 17 00:00:00 2001 From: Michael Vlach Date: Sun, 28 Jan 2024 11:48:38 +0100 Subject: [PATCH] [docs] Add API documentation #989 (#1015) * Update 2.quickstart.md * add api docs --- agdb_web/content/en/api/1.rust/index.md | 2 + agdb_web/content/en/api/2.typescript/index.md | 143 ++++++++++++++++++ .../content/en/docs/1.guides/2.quickstart.md | 8 +- docs/api.md | 2 +- 4 files changed, 150 insertions(+), 5 deletions(-) diff --git a/agdb_web/content/en/api/1.rust/index.md b/agdb_web/content/en/api/1.rust/index.md index c85a07594..d3804ef0d 100644 --- a/agdb_web/content/en/api/1.rust/index.md +++ b/agdb_web/content/en/api/1.rust/index.md @@ -8,3 +8,5 @@ navigation: # rust The rust agdb API client is **async only** and can be used with any HTTP client that would implement the `agdb_api::HttpClient` trait. The default implementation uses [reqwest](https://crates.io/crates/reqwest). + +See [Quickstart - client](/docs/guides/quickstart_client) for usage. diff --git a/agdb_web/content/en/api/2.typescript/index.md b/agdb_web/content/en/api/2.typescript/index.md index eb2c0e3a5..e682e6932 100644 --- a/agdb_web/content/en/api/2.typescript/index.md +++ b/agdb_web/content/en/api/2.typescript/index.md @@ -8,3 +8,146 @@ navigation: # typescript / javascript The typescript agdb API client is based on [openapi-client-axios](https://www.npmjs.com/package/openapi-client-axios). + +# Usage + +The following is the from-scratch guide to use `agdb-api` typescript/javascript package. + +1. Install [NodeJS](https://nodejs.org/en). + +2. Create your project's folder (e.g. `my_agdb`) and nitialize a package: + +```bash +mkdir my_agdb +cd my_agdb +npm init # follow the steps & prompts +``` + +3. Add `typescript` as your dev dependency: + +```bash +npm install typescript --save-dev +``` + +NOTE: Consider using other dev packages such as `prettier`, `eslint` (and `@typescript-eslint/parser`). + +4. Add `@agnesoft/agdb_api` npm package to your project: + +```bash +npm install @agnesoft/agdb_api +``` + +5. Create a `tsconfig.json` file: + +```json +{ + "compilerOptions": { + "module": "ESNext", + "sourceMap": true, + "lib": ["ES2015", "DOM"], + "moduleResolution": "node", + "allowJs": true, + "esModuleInterop": true + } +} +``` + +6. In your main script (`indes.ts` or `main.ts` depending on your `package.json`'s `"main"` field) create a client connecting to the server: + +```ts +import { QueryBuilder, AgdbApi } from "@agnesfot/agdb_api"; + +async function main() { + // Requires the server to be running... + + // Creates a client connecting to the remote server. + let client = await AgdbApi.client("http://localhost", 3000); +} +``` + +7. To create a user using the default admin user: + +```ts +let admin_token = await client.user_login(null, { + username: "admin", + password: "admin", +}); +AgdbApi.setToken(admin_token.data); +await client.admin_user_add("user1", { password: "password123" }); +let token = await client.user_login(null, { + username: "user1", + password: "password123", +}); +AgdbApi.setToken(token.data); //replaces the admin token +``` + +8. To create a database: + +```ts +await client.db_add({ + owner: "user1", + db: "db1", + db_type: "mapped", //memory mapped type, other options are "memory" and "file" +}); +``` + +9. To execute queries against the database. Notice we are feeding results of the previous query to the next one with special alias `":0"` and `":1"` referencing first and second result respectively: + +```ts +// Prepare the queries to be executed on the remote database. +let queries = [ + // :0: Inserts a root node aliase "users" + QueryBuilder.insert().nodes().aliases(["users"]).query(), + + // :1: Inserts more nodes with some data + QueryBuilder.insert() + .nodes() + .values([ + [ + { key: { String: "username" }, value: { String: "user1" } }, + { + key: { String: "password" }, + value: { String: "password123" }, + }, + ], + [ + { key: { String: "username" }, value: { String: "user1" } }, + { + key: { String: "password" }, + value: { String: "password456" }, + }, + ], + ]) + .query(), + + // :2: Connect the root to the inserted nodes with edges referencing both from previous queries + QueryBuilder.insert().edges().from(":0").to(":1").query(), + + // :3: Find a node starting at the "users" node (could also be ":0" in this instance) with specific username + QueryBuilder.select() + .ids( + QueryBuilder.search() + .from("users") + .where() + .key({ String: "username" }) + .value({ Equal: { String: "user1" } }) + .query(), + ) + .query(), +]; + +// Execute queries. +let results = (await client.db_exec({ owner: "user1", db: "db1" }, queries)) + .data; +``` + +10. Print the the result of the final query to the console: + +```ts +console.log(`User (id: ${results[3].elements[0].id})`); +for (let { key, value } of results[3].elements[0].values) { + console.log(`${key["String"]}: ${value["String"]}`); +} +``` + +11. See full program in the examples: https://github.com/agnesoft/agdb/tree/main/examples/server_client_typescript diff --git a/agdb_web/content/en/docs/1.guides/2.quickstart.md b/agdb_web/content/en/docs/1.guides/2.quickstart.md index f961f6719..1bd451579 100644 --- a/agdb_web/content/en/docs/1.guides/2.quickstart.md +++ b/agdb_web/content/en/docs/1.guides/2.quickstart.md @@ -63,9 +63,9 @@ db.exec_mut(&QueryBuilder::insert() #[derive(Debug, UserValue)] struct User { db_id: Option, // The db_id member is optional but - // it allows querying your user type - // from the database. - username: String + // it allows insert your user type + // directly into the database. + username: String, age: u64, } @@ -86,7 +86,7 @@ db.exec_mut( .edges() .from("users") .to(&db_users) // We can feed result of a previous - // query directly to the next one. + // query directly to the next one. .query(), )?; ``` diff --git a/docs/api.md b/docs/api.md index 2328ba733..0137d1c91 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,3 +1,3 @@ # API -TBD +[Follow the link](/agdb_web/content/en/api/index.md)