appwrite/docs/tutorials/add-route.md

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 and the Contributing Guide.

1. Alias

Setting an alias allows the route to be also accessible from the alias URL. The first parameter specifies the alias URL, the second parameter specifies default values for route parameters.

App::post('/v1/storage/buckets/:bucketId/files')
    ->alias('/v1/storage/files', ['bucketId' => 'default'])

2. Description

Used as an abstract description of the route.

App::post('/v1/storage/buckets/:bucketId/files')
    ->desc('Create File')

3. Groups

Groups array is used to group one or more routes with one or more hooks functionality.

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.

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 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. Appwrite uses different labels to achieve different things, for example:

Scope

• scope - Defines the route permissions scope.

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.

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 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.

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 true, signal the use of file cache.
• cache.resource - Identifies the cached resource.

App::get('/v1/storage/buckets/:bucketId/files/:fileId/preview')
    ->label('cache', true)
    ->label('cache.resource', 'file/{request.fileId}')

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 (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 combination of the ip, http method, url, userId to hit the route maximum 60 times in 1 hour (60 seconds * 60 minutes).

App::post('/v1/storage/buckets/:bucketId/files')
    ->label('abuse-key', 'ip:{ip},method:{method},url:{url},userId:{userId}')
    ->label('abuse-limit', 60)
    ->label('abuse-time', 3600)

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.

App::post('/v1/storage/buckets/:bucketId/files')
    ->label('event', 'buckets.[bucketId].files.[fileId].create')

Usage

• usage.metric - The metric the route generates.
• usage.params - Additional parameters the metrics can have.

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 implies, param() is used to define a request parameter.

param() accepts 6 parameters :

• A key (name)
• A default value
• 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

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.

App::post('/v1/storage/buckets/:bucketId/files')
    ->inject('user')

In the example above, the user object is injected into the route pre-bounded using App::setResource().

App::setResource('user', function() {
some code...
});

6. Action

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.

App::post('/v1/account/sessions/anonymous')
    ->action(function (Request $request) {
    some code...
});