From 9665d3a106af5e9021d0f21fc6916959a2cdfa63 Mon Sep 17 00:00:00 2001 From: shimon Date: Thu, 8 Sep 2022 16:13:00 +0300 Subject: [PATCH 01/28] add-route --- docs/tutorials/add-route.md | 218 ++++++++++++++++++++++++++++++++++++ 1 file changed, 218 insertions(+) create mode 100644 docs/tutorials/add-route.md diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md new file mode 100644 index 0000000000..5049d13695 --- /dev/null +++ b/docs/tutorials/add-route.md @@ -0,0 +1,218 @@ +# Adding route 🛡 + +This document is part of the Appwrite contributors' guide. Before you continue reading this document make sure you have read the [Code of Conduct](https://github.com/appwrite/appwrite/blob/master/CODE_OF_CONDUCT.md) and the [Contributing Guide](https://github.com/appwrite/appwrite/blob/master/CONTRIBUTING.md). + +### 1. Alias +Setting an alias is used to permit access the route from an alias url as well +second parameter is used to push default values to the route. +```php +App::post('/v1/storage/buckets/:bucketId/files') + ->alias('/v1/storage/files', ['bucketId' => 'default']) +``` + +### 2. desc +Used for an abstract description of the route in a couple of words. +```php +App::post('/v1/storage/buckets/:bucketId/files') +->desc('Create File') +``` + +### 3. Groups +The groups array is used to group one or more routes with one or more hooks functionality. +```php +App::post('/v1/storage/buckets/:bucketId/files') +->groups(['api']) +``` +In the above example groups() is used to define the current route as part of the routes that shares a common init middleware hook. +```php +App::init() +->groups(['api']) +->action( + some code..... +); +``` + + +### 4. The labels mechanism +Labels are very strait forward and easy to use and understand, but in the same time very robust. +Labels are passed from the controllers route, and used to pick up key value pairs to be handled in a centralized place +along the road. +Labels can be used to pass a pattern in order to be replaced in the other end. +Appwrite uses different labels to achieve different things, for example: + +### Scope +* scope - Defines the route permissions scope. + +```php +App::post('/v1/storage/buckets/:bucketId/files') + ->label('scope', 'files.write') +``` + +### Audit +* audits.event - Identify the log in human-readable text. +* audits.userId - Signals the extraction of $userId in places that it's not available natively. +* audits.resource - Signals the extraction part of the resource. + + +```php +App::post('/v1/account/create') +->label('audits.event', 'account.create') +->label('audits.resource', 'user/{response.$id}') +->label('audits.userId', '{response.$id}') +``` + +### Sdk +* sdk.auth - Array of authentication types is passed in order to impose different authentication methods in different situations. +* sdk.namespace - Refers to the route namespace. +* sdk.method - Refers to the sdk method that needs to called. +* sdk.description - Description of the route, using md file format. +* sdk.sdk.response.code - Refers to the route http response status code expected. +* sdk.auth.response.model - Refers the route http response expected. + +```php +App::post('/v1/account/jwt') +->label('sdk.auth', [APP_AUTH_TYPE_SESSION]) +->label('sdk.namespace', 'account') +->label('sdk.method', 'createJWT') +->label('sdk.description', '/docs/references/account/create-jwt.md') +->label('sdk.response.code', Response::STATUS_CODE_CREATED) +->label('sdk.response.type', Response::CONTENT_TYPE_JSON) +->label('sdk.response.model', Response::MODEL_JWT) +``` + +### Cache +* cache - When set to ture, signal the use of file cache. +* cache.resource - Identifies the cached resource. + +```php +App::get('/v1/storage/buckets/:bucketId/files/:fileId/preview') +->label('cache', true) +->label('cache.resource', 'file/{request.fileId}') +``` + +### Abuse +* abuse-key - Specifies routes uniq abuse key. +* abuse-limit - Specifies the number of times the route can be requested in a time frame, per route. +* abuse-time - Specifies the time frame relevancy of the all other abuse definitions, per route. + +```php +App::post('/v1/storage/buckets/:bucketId/files') + ->label('abuse-key', 'ip:{ip},method:{method},url:{url},userId:{userId}') + ->label('abuse-limit', APP_LIMIT_WRITE_RATE_DEFAULT) + ->label('abuse-time', APP_LIMIT_WRITE_RATE_PERIOD_DEFAULT) +``` + +### Events +* event - A pattern that is associated with the route in behalf of realtime messaging. + Placeholders marked as [] are parsed and replaced with their real values. + +```php +App::post('/v1/storage/buckets/:bucketId/files') + ->label('event', 'buckets.[bucketId].files.[fileId].create') +``` + +### Usage +* usage.metric - . +* usage.params - . +```php +App::post('/v1/storage/buckets/:bucketId/files') + ->label('usage.metric', 'files.{scope}.requests.create') + ->label('usage.params', ['bucketId:{request.bucketId}']) +``` + +### 5. Param +As the name applies param() is used to setting up a request parameter. + +param() aspects 7 parameters : +* A key (name) +* A default value +* An instance of a relevant validator class +* Description of the parameter +* Is the route optional +* An array of injections +```php +App::get('/v1/account/logs') + ->param('queries', [], new Queries(new Limit(), new Offset()), 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/databases#querying-documents). Only supported methods are limit and offset', true) +``` + + +### 6. inject +inject is used to inject dependencies pre bounded to the app. + +```php +App::post('/v1/storage/buckets/:bucketId/files') +->inject('user') +``` + +In the example above user object is injected to the route pre bounded using App::setResource(). + +```php +App::setResource('user', function() { +some code... +}); +``` + +### 6. Action +Action populates the actual routes code and has to be very clear and understandable. + +```php +App::post('/v1/account/sessions/anonymous') + ->action(function (Request $request) { + some code... +}); +``` + + + + +/v1/databases/:databaseId/collections/:collectionId/attributes/string +->label('audits.event', 'attribute.create') +App::patch('/v1/teams/:teamId/memberships/:membershipId/status') +App::patch('/v1/teams/:teamId/memberships/:membershipId') +->label('audits.event', 'membership.update') + +App::patch('/v1/account/name') +App::patch('/v1/account/password') +App::patch('/v1/account/email') +App::patch('/v1/account/phone') +App::patch('/v1/account/prefs') +App::patch('/v1/account/status') +->label('audits.event', 'account.update') + +App::delete('/v1/account/sessions') +App::delete('/v1/account/sessions/:sessionId') +App::delete('/v1/users/:userId/sessions/:sessionId') +App::delete('/v1/users/:userId/sessions') +->label('audits.event', 'session.delete') + + +App::post('/v1/account/verification/phone') +App::post('/v1/account/verification/email') +->label('audits.event', 'verification.create') + +App::patch('/v1/users/:userId/name') +App::put('/v1/account/verification/phone') +App::put('/v1/account/verification/email') +App::patch('/v1/users/:userId/verification') +App::patch('/v1/users/:userId/verification/phone') +App::patch('/v1/users/:userId/verification') +->label('audits.event', 'verification.update') + + + + +App::post('/v1/account/sessions/anonymous') +App::post('/v1/account/sessions/phone') + + +App::post('/v1/users') +App::post('/v1/users/bcrypt') +App::post('/v1/users/argon2') +App::post('/v1/users/sha') +->label('audits.event', 'user.create') + + +App::patch('/v1/users/:userId/password') +App::patch('/v1/users/:userId/email') +App::patch('/v1/users/:userId/phone') +->label('audits.event', 'user.update') \ No newline at end of file From 812cd9be765715db90a3c0cab29c745d13218e4d Mon Sep 17 00:00:00 2001 From: shimon Date: Thu, 8 Sep 2022 16:18:56 +0300 Subject: [PATCH 02/28] add-route --- docs/tutorials/add-route.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index 5049d13695..a0e1f77e5a 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -3,7 +3,7 @@ This document is part of the Appwrite contributors' guide. Before you continue reading this document make sure you have read the [Code of Conduct](https://github.com/appwrite/appwrite/blob/master/CODE_OF_CONDUCT.md) and the [Contributing Guide](https://github.com/appwrite/appwrite/blob/master/CONTRIBUTING.md). ### 1. Alias -Setting an alias is used to permit access the route from an alias url as well +Setting an alias is used to permit access the route from an alias url as well, second parameter is used to push default values to the route. ```php App::post('/v1/storage/buckets/:bucketId/files') @@ -11,14 +11,14 @@ App::post('/v1/storage/buckets/:bucketId/files') ``` ### 2. desc -Used for an abstract description of the route in a couple of words. +Used as an abstract description of the route. ```php App::post('/v1/storage/buckets/:bucketId/files') ->desc('Create File') ``` ### 3. Groups -The groups array is used to group one or more routes with one or more hooks functionality. +Groups array is used to group one or more routes with one or more hooks functionality. ```php App::post('/v1/storage/buckets/:bucketId/files') ->groups(['api']) From 6507bf9fadee914ea8501d647024428f9b9f1f36 Mon Sep 17 00:00:00 2001 From: shimon Date: Thu, 8 Sep 2022 16:36:39 +0300 Subject: [PATCH 03/28] add-route --- docs/tutorials/add-route.md | 55 ------------------------------------- 1 file changed, 55 deletions(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index a0e1f77e5a..f5c2a95c3d 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -161,58 +161,3 @@ App::post('/v1/account/sessions/anonymous') some code... }); ``` - - - - -/v1/databases/:databaseId/collections/:collectionId/attributes/string -->label('audits.event', 'attribute.create') -App::patch('/v1/teams/:teamId/memberships/:membershipId/status') -App::patch('/v1/teams/:teamId/memberships/:membershipId') -->label('audits.event', 'membership.update') - -App::patch('/v1/account/name') -App::patch('/v1/account/password') -App::patch('/v1/account/email') -App::patch('/v1/account/phone') -App::patch('/v1/account/prefs') -App::patch('/v1/account/status') -->label('audits.event', 'account.update') - -App::delete('/v1/account/sessions') -App::delete('/v1/account/sessions/:sessionId') -App::delete('/v1/users/:userId/sessions/:sessionId') -App::delete('/v1/users/:userId/sessions') -->label('audits.event', 'session.delete') - - -App::post('/v1/account/verification/phone') -App::post('/v1/account/verification/email') -->label('audits.event', 'verification.create') - -App::patch('/v1/users/:userId/name') -App::put('/v1/account/verification/phone') -App::put('/v1/account/verification/email') -App::patch('/v1/users/:userId/verification') -App::patch('/v1/users/:userId/verification/phone') -App::patch('/v1/users/:userId/verification') -->label('audits.event', 'verification.update') - - - - -App::post('/v1/account/sessions/anonymous') -App::post('/v1/account/sessions/phone') - - -App::post('/v1/users') -App::post('/v1/users/bcrypt') -App::post('/v1/users/argon2') -App::post('/v1/users/sha') -->label('audits.event', 'user.create') - - -App::patch('/v1/users/:userId/password') -App::patch('/v1/users/:userId/email') -App::patch('/v1/users/:userId/phone') -->label('audits.event', 'user.update') \ No newline at end of file From 4cd0f4ea1e8747da75d9c42bbe9a0fd5fed578ac Mon Sep 17 00:00:00 2001 From: Shimon Newman Date: Fri, 9 Sep 2022 16:02:01 +0300 Subject: [PATCH 04/28] Update docs/tutorials/add-route.md Co-authored-by: Vincent (Wen Yu) Ge --- docs/tutorials/add-route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index f5c2a95c3d..d0840649bc 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -1,4 +1,4 @@ -# Adding route 🛡 +# Adding Route 🛡 This document is part of the Appwrite contributors' guide. Before you continue reading this document make sure you have read the [Code of Conduct](https://github.com/appwrite/appwrite/blob/master/CODE_OF_CONDUCT.md) and the [Contributing Guide](https://github.com/appwrite/appwrite/blob/master/CONTRIBUTING.md). From 3e23759e696770add2fdef7cbc4e35596b1f4213 Mon Sep 17 00:00:00 2001 From: Shimon Newman Date: Fri, 9 Sep 2022 16:02:21 +0300 Subject: [PATCH 05/28] Update docs/tutorials/add-route.md Co-authored-by: Vincent (Wen Yu) Ge --- docs/tutorials/add-route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index d0840649bc..aa33e7bd5e 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -3,7 +3,7 @@ This document is part of the Appwrite contributors' guide. Before you continue reading this document make sure you have read the [Code of Conduct](https://github.com/appwrite/appwrite/blob/master/CODE_OF_CONDUCT.md) and the [Contributing Guide](https://github.com/appwrite/appwrite/blob/master/CONTRIBUTING.md). ### 1. Alias -Setting an alias is used to permit access the route from an alias url as well, +Setting an alias allows the route to be also accessible from the alias URL. second parameter is used to push default values to the route. ```php App::post('/v1/storage/buckets/:bucketId/files') From 4809520462d8bd7aac2464537f88d6209ec8ae32 Mon Sep 17 00:00:00 2001 From: Shimon Newman Date: Fri, 9 Sep 2022 16:02:58 +0300 Subject: [PATCH 06/28] Update docs/tutorials/add-route.md Co-authored-by: Vincent (Wen Yu) Ge --- docs/tutorials/add-route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index aa33e7bd5e..0c1e18f0d4 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -10,7 +10,7 @@ App::post('/v1/storage/buckets/:bucketId/files') ->alias('/v1/storage/files', ['bucketId' => 'default']) ``` -### 2. desc +### 2. Description Used as an abstract description of the route. ```php App::post('/v1/storage/buckets/:bucketId/files') From d865b5adee910daaf1e2f3a2c9e5bc68fb2ee54c Mon Sep 17 00:00:00 2001 From: Shimon Newman Date: Fri, 9 Sep 2022 16:03:09 +0300 Subject: [PATCH 07/28] Update docs/tutorials/add-route.md Co-authored-by: Vincent (Wen Yu) Ge --- docs/tutorials/add-route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index 0c1e18f0d4..c7c2b69eff 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -144,7 +144,7 @@ App::post('/v1/storage/buckets/:bucketId/files') ->inject('user') ``` -In the example above user object is injected to the route pre bounded using App::setResource(). +In the example above, the user object is injected into the route pre-bounded using `App::setResource()`. ```php App::setResource('user', function() { From 9c0da69dbb9f8482cda2fd9750a52c5616ebb5a1 Mon Sep 17 00:00:00 2001 From: Shimon Newman Date: Fri, 9 Sep 2022 16:03:28 +0300 Subject: [PATCH 08/28] Update docs/tutorials/add-route.md Co-authored-by: Vincent (Wen Yu) Ge --- docs/tutorials/add-route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index c7c2b69eff..e18d186fd3 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -121,7 +121,7 @@ App::post('/v1/storage/buckets/:bucketId/files') ``` ### 5. Param -As the name applies param() is used to setting up a request parameter. +As the name implies, `param()` is used to define a request parameter. param() aspects 7 parameters : * A key (name) From 101e6cb539d8e6f1643b304bc7cfd852b0d60dd8 Mon Sep 17 00:00:00 2001 From: Shimon Newman Date: Fri, 9 Sep 2022 16:03:37 +0300 Subject: [PATCH 09/28] Update docs/tutorials/add-route.md Co-authored-by: Vincent (Wen Yu) Ge --- docs/tutorials/add-route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index e18d186fd3..d96f20367e 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -137,7 +137,7 @@ App::get('/v1/account/logs') ### 6. inject -inject is used to inject dependencies pre bounded to the app. +inject is used to inject dependencies pre-bounded to the app. ```php App::post('/v1/storage/buckets/:bucketId/files') From 2ef98752dc61cba6c82d5385719fd0dd63736077 Mon Sep 17 00:00:00 2001 From: Shimon Newman Date: Fri, 9 Sep 2022 16:04:00 +0300 Subject: [PATCH 10/28] Update docs/tutorials/add-route.md Co-authored-by: Vincent (Wen Yu) Ge --- docs/tutorials/add-route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index d96f20367e..4c01b29731 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -11,7 +11,7 @@ App::post('/v1/storage/buckets/:bucketId/files') ``` ### 2. Description -Used as an abstract description of the route. +Used as an abstract description of the route. ```php App::post('/v1/storage/buckets/:bucketId/files') ->desc('Create File') From f28248037caa098d8c77afb1a3e0cbef1dadd420 Mon Sep 17 00:00:00 2001 From: Shimon Newman Date: Fri, 9 Sep 2022 16:04:13 +0300 Subject: [PATCH 11/28] Update docs/tutorials/add-route.md Co-authored-by: Vincent (Wen Yu) Ge --- docs/tutorials/add-route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index 4c01b29731..4b6fa4bbba 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -4,7 +4,7 @@ This document is part of the Appwrite contributors' guide. Before you continue r ### 1. Alias Setting an alias allows the route to be also accessible from the alias URL. -second parameter is used to push default values to the route. +The first parameter specifies the alias URL, the second parameter specifies default values for route parameters. ```php App::post('/v1/storage/buckets/:bucketId/files') ->alias('/v1/storage/files', ['bucketId' => 'default']) From 10b02771206a6b3b832512e75bb020aaccc7791a Mon Sep 17 00:00:00 2001 From: Shimon Newman Date: Fri, 9 Sep 2022 16:04:39 +0300 Subject: [PATCH 12/28] Update docs/tutorials/add-route.md Co-authored-by: Vincent (Wen Yu) Ge --- docs/tutorials/add-route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index 4b6fa4bbba..36e2225298 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -33,7 +33,7 @@ App::init() ``` -### 4. The labels mechanism +### 4. The Labels Mechanism Labels are very strait forward and easy to use and understand, but in the same time very robust. Labels are passed from the controllers route, and used to pick up key value pairs to be handled in a centralized place along the road. From 16024e0020c6132bff0fd8fd47decbdf78fb1c65 Mon Sep 17 00:00:00 2001 From: Shimon Newman Date: Fri, 9 Sep 2022 16:04:52 +0300 Subject: [PATCH 13/28] Update docs/tutorials/add-route.md Co-authored-by: Vincent (Wen Yu) Ge --- docs/tutorials/add-route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index 36e2225298..3ec423ece3 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -35,7 +35,7 @@ App::init() ### 4. The Labels Mechanism Labels are very strait forward and easy to use and understand, but in the same time very robust. -Labels are passed from the controllers route, and used to pick up key value pairs to be handled in a centralized place +Labels are passed from the controllers route and used to pick up key-value pairs to be handled in a centralized place along the road. Labels can be used to pass a pattern in order to be replaced in the other end. Appwrite uses different labels to achieve different things, for example: From 19a59457302d025a55c7449a951487c4a308c9dd Mon Sep 17 00:00:00 2001 From: Shimon Newman Date: Fri, 9 Sep 2022 16:05:16 +0300 Subject: [PATCH 14/28] Update docs/tutorials/add-route.md Co-authored-by: Vincent (Wen Yu) Ge --- docs/tutorials/add-route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index 3ec423ece3..9f20fb01ac 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -40,7 +40,7 @@ along the road. Labels can be used to pass a pattern in order to be replaced in the other end. Appwrite uses different labels to achieve different things, for example: -### Scope +#### Scope * scope - Defines the route permissions scope. ```php From a698dfde8be7df032ae35f3b2ad41f62de725d83 Mon Sep 17 00:00:00 2001 From: Shimon Newman Date: Fri, 9 Sep 2022 16:05:42 +0300 Subject: [PATCH 15/28] Update docs/tutorials/add-route.md Co-authored-by: Vincent (Wen Yu) Ge --- docs/tutorials/add-route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index 9f20fb01ac..9ee1097125 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -48,7 +48,7 @@ App::post('/v1/storage/buckets/:bucketId/files') ->label('scope', 'files.write') ``` -### Audit +#### Audit * audits.event - Identify the log in human-readable text. * audits.userId - Signals the extraction of $userId in places that it's not available natively. * audits.resource - Signals the extraction part of the resource. From 910c37729d06aaccbb78bdb15350968f004041fa Mon Sep 17 00:00:00 2001 From: Shimon Newman Date: Fri, 9 Sep 2022 16:05:59 +0300 Subject: [PATCH 16/28] Update docs/tutorials/add-route.md Co-authored-by: Vincent (Wen Yu) Ge --- docs/tutorials/add-route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index 9ee1097125..a9c08ccb41 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -61,7 +61,7 @@ App::post('/v1/account/create') ->label('audits.userId', '{response.$id}') ``` -### Sdk +#### SDK * sdk.auth - Array of authentication types is passed in order to impose different authentication methods in different situations. * sdk.namespace - Refers to the route namespace. * sdk.method - Refers to the sdk method that needs to called. From 09e5e0661470469ccb4e41b3acd03b2c951aade4 Mon Sep 17 00:00:00 2001 From: Shimon Newman Date: Fri, 9 Sep 2022 16:06:20 +0300 Subject: [PATCH 17/28] Update docs/tutorials/add-route.md Co-authored-by: Vincent (Wen Yu) Ge --- docs/tutorials/add-route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index a9c08ccb41..d15590bfc8 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -65,7 +65,7 @@ App::post('/v1/account/create') * sdk.auth - Array of authentication types is passed in order to impose different authentication methods in different situations. * sdk.namespace - Refers to the route namespace. * sdk.method - Refers to the sdk method that needs to called. -* sdk.description - Description of the route, using md file format. +* sdk.description - Description of the route,using markdown format. * sdk.sdk.response.code - Refers to the route http response status code expected. * sdk.auth.response.model - Refers the route http response expected. From f494ec488f58988ef59aab54ab20599bf6702674 Mon Sep 17 00:00:00 2001 From: Shimon Newman Date: Fri, 9 Sep 2022 16:06:38 +0300 Subject: [PATCH 18/28] Update docs/tutorials/add-route.md Co-authored-by: Vincent (Wen Yu) Ge --- docs/tutorials/add-route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index d15590bfc8..f065afb601 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -81,7 +81,7 @@ App::post('/v1/account/jwt') ``` ### Cache -* cache - When set to ture, signal the use of file cache. +* cache - When set to true, signal the use of file cache. * cache.resource - Identifies the cached resource. ```php From 016de0235626288e4d188baccee6a20021c67940 Mon Sep 17 00:00:00 2001 From: Shimon Newman Date: Fri, 9 Sep 2022 16:06:52 +0300 Subject: [PATCH 19/28] Update docs/tutorials/add-route.md Co-authored-by: Vincent (Wen Yu) Ge --- docs/tutorials/add-route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index f065afb601..55595e0b02 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -91,7 +91,7 @@ App::get('/v1/storage/buckets/:bucketId/files/:fileId/preview') ``` ### Abuse -* abuse-key - Specifies routes uniq abuse key. +* abuse-key - Specifies routes unique abuse key. * abuse-limit - Specifies the number of times the route can be requested in a time frame, per route. * abuse-time - Specifies the time frame relevancy of the all other abuse definitions, per route. From cd058633f502f954049bf51d8dbb640de28dda55 Mon Sep 17 00:00:00 2001 From: Shimon Newman Date: Fri, 9 Sep 2022 16:07:09 +0300 Subject: [PATCH 20/28] Update docs/tutorials/add-route.md Co-authored-by: Vincent (Wen Yu) Ge --- docs/tutorials/add-route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index 55595e0b02..fea4ae5a68 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -104,7 +104,7 @@ App::post('/v1/storage/buckets/:bucketId/files') ### Events * event - A pattern that is associated with the route in behalf of realtime messaging. - Placeholders marked as [] are parsed and replaced with their real values. + Placeholders marked as `[]` are parsed and replaced with their real values. ```php App::post('/v1/storage/buckets/:bucketId/files') From edb4ca6a631fc776b55d7bc921ed82897f42b936 Mon Sep 17 00:00:00 2001 From: shimon Date: Fri, 9 Sep 2022 16:15:38 +0300 Subject: [PATCH 21/28] Tidy up --- docs/tutorials/add-route.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index fea4ae5a68..8c1e2fb27f 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -112,8 +112,8 @@ App::post('/v1/storage/buckets/:bucketId/files') ``` ### Usage -* usage.metric - . -* usage.params - . +* usage.metric - The metric the route generates. +* usage.params - Additional parameters the metrics can have. ```php App::post('/v1/storage/buckets/:bucketId/files') ->label('usage.metric', 'files.{scope}.requests.create') From 947e4190d566b4f107114a1e5b7621237c7ae708 Mon Sep 17 00:00:00 2001 From: shimon Date: Fri, 9 Sep 2022 16:21:26 +0300 Subject: [PATCH 22/28] Tidy up --- docs/tutorials/add-route.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index 8c1e2fb27f..8586552a9e 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -34,7 +34,7 @@ App::init() ### 4. The Labels Mechanism -Labels are very strait forward and easy to use and understand, but in the same time very robust. +Labels are very strait forward and easy to use and understand, but in the same time are very robust. Labels are passed from the controllers route and used to pick up key-value pairs to be handled in a centralized place along the road. Labels can be used to pass a pattern in order to be replaced in the other end. @@ -61,7 +61,7 @@ App::post('/v1/account/create') ->label('audits.userId', '{response.$id}') ``` -#### SDK +#### Sdk * sdk.auth - Array of authentication types is passed in order to impose different authentication methods in different situations. * sdk.namespace - Refers to the route namespace. * sdk.method - Refers to the sdk method that needs to called. @@ -80,7 +80,7 @@ App::post('/v1/account/jwt') ->label('sdk.response.model', Response::MODEL_JWT) ``` -### Cache +#### Cache * cache - When set to true, signal the use of file cache. * cache.resource - Identifies the cached resource. @@ -90,7 +90,7 @@ App::get('/v1/storage/buckets/:bucketId/files/:fileId/preview') ->label('cache.resource', 'file/{request.fileId}') ``` -### Abuse +#### Abuse * abuse-key - Specifies routes unique abuse key. * abuse-limit - Specifies the number of times the route can be requested in a time frame, per route. * abuse-time - Specifies the time frame relevancy of the all other abuse definitions, per route. @@ -102,7 +102,7 @@ App::post('/v1/storage/buckets/:bucketId/files') ->label('abuse-time', APP_LIMIT_WRITE_RATE_PERIOD_DEFAULT) ``` -### Events +#### Events * event - A pattern that is associated with the route in behalf of realtime messaging. Placeholders marked as `[]` are parsed and replaced with their real values. @@ -111,7 +111,7 @@ App::post('/v1/storage/buckets/:bucketId/files') ->label('event', 'buckets.[bucketId].files.[fileId].create') ``` -### Usage +#### Usage * usage.metric - The metric the route generates. * usage.params - Additional parameters the metrics can have. ```php From ef7f919fa175e093fb67f004b4c80d9d263adb99 Mon Sep 17 00:00:00 2001 From: shimon Date: Fri, 9 Sep 2022 16:40:34 +0300 Subject: [PATCH 23/28] Tidy up --- docs/tutorials/add-route.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index 8586552a9e..35269ad185 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -14,7 +14,7 @@ App::post('/v1/storage/buckets/:bucketId/files') Used as an abstract description of the route. ```php App::post('/v1/storage/buckets/:bucketId/files') -->desc('Create File') + ->desc('Create File') ``` ### 3. Groups @@ -26,8 +26,8 @@ App::post('/v1/storage/buckets/:bucketId/files') In the above example groups() is used to define the current route as part of the routes that shares a common init middleware hook. ```php App::init() -->groups(['api']) -->action( + ->groups(['api']) + ->action( some code..... ); ``` @@ -56,12 +56,12 @@ App::post('/v1/storage/buckets/:bucketId/files') ```php App::post('/v1/account/create') -->label('audits.event', 'account.create') -->label('audits.resource', 'user/{response.$id}') -->label('audits.userId', '{response.$id}') + ->label('audits.event', 'account.create') + ->label('audits.resource', 'user/{response.$id}') + ->label('audits.userId', '{response.$id}') ``` -#### Sdk +#### SDK * sdk.auth - Array of authentication types is passed in order to impose different authentication methods in different situations. * sdk.namespace - Refers to the route namespace. * sdk.method - Refers to the sdk method that needs to called. @@ -71,13 +71,13 @@ App::post('/v1/account/create') ```php App::post('/v1/account/jwt') -->label('sdk.auth', [APP_AUTH_TYPE_SESSION]) -->label('sdk.namespace', 'account') -->label('sdk.method', 'createJWT') -->label('sdk.description', '/docs/references/account/create-jwt.md') -->label('sdk.response.code', Response::STATUS_CODE_CREATED) -->label('sdk.response.type', Response::CONTENT_TYPE_JSON) -->label('sdk.response.model', Response::MODEL_JWT) + ->label('sdk.auth', [APP_AUTH_TYPE_SESSION]) + ->label('sdk.namespace', 'account') + ->label('sdk.method', 'createJWT') + ->label('sdk.description', '/docs/references/account/create-jwt.md') + ->label('sdk.response.code', Response::STATUS_CODE_CREATED) + ->label('sdk.response.type', Response::CONTENT_TYPE_JSON) + ->label('sdk.response.model', Response::MODEL_JWT) ``` #### Cache @@ -86,8 +86,8 @@ App::post('/v1/account/jwt') ```php App::get('/v1/storage/buckets/:bucketId/files/:fileId/preview') -->label('cache', true) -->label('cache.resource', 'file/{request.fileId}') + ->label('cache', true) + ->label('cache.resource', 'file/{request.fileId}') ``` #### Abuse @@ -132,7 +132,7 @@ param() aspects 7 parameters : * An array of injections ```php App::get('/v1/account/logs') - ->param('queries', [], new Queries(new Limit(), new Offset()), 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/databases#querying-documents). Only supported methods are limit and offset', true) + ->param('queries', [], new Queries(new Limit(), new Offset()), 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/databases#querying-documents). Only supported methods are limit and offset', true) ``` @@ -141,7 +141,7 @@ inject is used to inject dependencies pre-bounded to the app. ```php App::post('/v1/storage/buckets/:bucketId/files') -->inject('user') + ->inject('user') ``` In the example above, the user object is injected into the route pre-bounded using `App::setResource()`. From 3f568f732ed6720e7f4bac22d7b545a9a7689ea1 Mon Sep 17 00:00:00 2001 From: Shimon Newman Date: Fri, 9 Sep 2022 16:43:17 +0300 Subject: [PATCH 24/28] Update docs/tutorials/add-route.md Co-authored-by: Eldad A. Fux --- docs/tutorials/add-route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index 35269ad185..f6c72c9376 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -153,7 +153,7 @@ some code... ``` ### 6. Action -Action populates the actual routes code and has to be very clear and understandable. +Action populates the actual routes code and has to be very clear and understandable. A good route stay simple and doesn't contain complex logic. An action is where we describe our business need in code, and combine different libraries to work together and tell our story. ```php App::post('/v1/account/sessions/anonymous') From 963ce8198ebad78f72de4a2ea9cabff5d0c52a7e Mon Sep 17 00:00:00 2001 From: shimon Date: Fri, 9 Sep 2022 17:00:08 +0300 Subject: [PATCH 25/28] Tidy up --- docs/tutorials/add-route.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index 35269ad185..7d00fc6cb2 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -93,13 +93,16 @@ App::get('/v1/storage/buckets/:bucketId/files/:fileId/preview') #### Abuse * abuse-key - Specifies routes unique abuse key. * abuse-limit - Specifies the number of times the route can be requested in a time frame, per route. -* abuse-time - Specifies the time frame relevancy of the all other abuse definitions, per route. +* abuse-time - Specifies the time frame (in seconds) relevancy of the all other abuse definitions, per route. + +When using the example below, we configure the abuse mechanism to allow this key combination +constructed from the uniq combination of the ip, http method, url, userId to hit the route maximum 60 times in 1 hour (60 seconds * 60 minutes). ```php App::post('/v1/storage/buckets/:bucketId/files') ->label('abuse-key', 'ip:{ip},method:{method},url:{url},userId:{userId}') - ->label('abuse-limit', APP_LIMIT_WRITE_RATE_DEFAULT) - ->label('abuse-time', APP_LIMIT_WRITE_RATE_PERIOD_DEFAULT) + ->label('abuse-limit', 60) + ->label('abuse-time', 3600) ``` #### Events From b757951f9ca9dcc84ee02155c5718164a579b816 Mon Sep 17 00:00:00 2001 From: shimon Date: Fri, 9 Sep 2022 17:01:45 +0300 Subject: [PATCH 26/28] Tidy up --- docs/tutorials/add-route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index abd8c0638a..faded859c2 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -126,7 +126,7 @@ App::post('/v1/storage/buckets/:bucketId/files') ### 5. Param As the name implies, `param()` is used to define a request parameter. -param() aspects 7 parameters : +param() accepts 7 parameters : * A key (name) * A default value * An instance of a relevant validator class From dc36f05ee76712e5a22db60590fb23690602ee67 Mon Sep 17 00:00:00 2001 From: shimon Date: Fri, 9 Sep 2022 17:29:11 +0300 Subject: [PATCH 27/28] Tidy up --- docs/tutorials/add-route.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index faded859c2..f42dc020b9 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -96,7 +96,7 @@ App::get('/v1/storage/buckets/:bucketId/files/:fileId/preview') * abuse-time - Specifies the time frame (in seconds) relevancy of the all other abuse definitions, per route. When using the example below, we configure the abuse mechanism to allow this key combination -constructed from the uniq combination of the ip, http method, url, userId to hit the route maximum 60 times in 1 hour (60 seconds * 60 minutes). +constructed from the combination of the ip, http method, url, userId to hit the route maximum 60 times in 1 hour (60 seconds * 60 minutes). ```php App::post('/v1/storage/buckets/:bucketId/files') @@ -126,13 +126,14 @@ App::post('/v1/storage/buckets/:bucketId/files') ### 5. Param As the name implies, `param()` is used to define a request parameter. -param() accepts 7 parameters : +`param()` accepts 6 parameters : * A key (name) * A default value -* An instance of a relevant validator class +* An instance of a validator class,This can also accept a callback that returns a validator instance. Dependency injection is supported for the callback. * Description of the parameter * Is the route optional * An array of injections + ```php App::get('/v1/account/logs') ->param('queries', [], new Queries(new Limit(), new Offset()), 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/databases#querying-documents). Only supported methods are limit and offset', true) From 48b3d825183b5b6f38a0c445b974b3533994d660 Mon Sep 17 00:00:00 2001 From: shimon Date: Fri, 9 Sep 2022 17:30:37 +0300 Subject: [PATCH 28/28] Tidy up --- docs/tutorials/add-route.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/add-route.md b/docs/tutorials/add-route.md index f42dc020b9..6b1bf7e7cf 100644 --- a/docs/tutorials/add-route.md +++ b/docs/tutorials/add-route.md @@ -21,7 +21,7 @@ App::post('/v1/storage/buckets/:bucketId/files') Groups array is used to group one or more routes with one or more hooks functionality. ```php App::post('/v1/storage/buckets/:bucketId/files') -->groups(['api']) + ->groups(['api']) ``` In the above example groups() is used to define the current route as part of the routes that shares a common init middleware hook. ```php