2022-09-10 01:02:01 +12:00
# Adding Route 🛡
2022-09-09 01:13:00 +12:00
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
2022-09-10 01:02:21 +12:00
Setting an alias allows the route to be also accessible from the alias URL.
2022-09-10 01:04:13 +12:00
The first parameter specifies the alias URL, the second parameter specifies default values for route parameters.
2022-09-09 01:13:00 +12:00
```php
App::post('/v1/storage/buckets/:bucketId/files')
->alias('/v1/storage/files', ['bucketId' => 'default'])
```
2022-09-10 01:02:58 +12:00
### 2. Description
2022-09-10 01:04:00 +12:00
Used as an abstract description of the route.
2022-09-09 01:13:00 +12:00
```php
App::post('/v1/storage/buckets/:bucketId/files')
->desc('Create File')
```
### 3. Groups
2022-09-09 01:18:56 +12:00
Groups array is used to group one or more routes with one or more hooks functionality.
2022-09-09 01:13:00 +12:00
```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.....
);
```
2022-09-10 01:04:39 +12:00
### 4. The Labels Mechanism
2022-09-09 01:13:00 +12:00
Labels are very strait forward and easy to use and understand, but in the same time very robust.
2022-09-10 01:04:52 +12:00
Labels are passed from the controllers route and used to pick up key-value pairs to be handled in a centralized place
2022-09-09 01:13:00 +12:00
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:
2022-09-10 01:05:16 +12:00
#### Scope
2022-09-09 01:13:00 +12:00
* scope - Defines the route permissions scope.
```php
App::post('/v1/storage/buckets/:bucketId/files')
->label('scope', 'files.write')
```
2022-09-10 01:05:42 +12:00
#### Audit
2022-09-09 01:13:00 +12:00
* 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}')
```
2022-09-10 01:05:59 +12:00
#### SDK
2022-09-09 01:13:00 +12:00
* 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
2022-09-10 01:03:28 +12:00
As the name implies, `param()` is used to define a request parameter.
2022-09-09 01:13:00 +12:00
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
2022-09-10 01:03:37 +12:00
inject is used to inject dependencies pre-bounded to the app.
2022-09-09 01:13:00 +12:00
```php
App::post('/v1/storage/buckets/:bucketId/files')
->inject('user')
```
2022-09-10 01:03:09 +12:00
In the example above, the user object is injected into the route pre-bounded using `App::setResource()` .
2022-09-09 01:13:00 +12:00
```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...
});
```