Merge pull request #7667 from appwrite/1.5.x-api-descriptions

1.5.x api descriptions

app/console

@@ -1 +1 @@
-Subproject commit c72ba12e479b0d3d9b3f4e48e01625c12a38fd7f
+Subproject commit f196bcfb485adfb36324aabf32a3449471319bbd

app/controllers/api/account.php

@@ -2700,7 +2700,7 @@ App::delete('/v1/account/sessions/:sessionId')
     });
 
 App::patch('/v1/account/sessions/:sessionId')
-    ->desc('Update (or renew) a session')
+    ->desc('Update (or renew) session')
     ->groups(['api', 'account'])
     ->label('scope', 'account')
     ->label('event', 'users.[userId].sessions.[sessionId].update')
@@ -4024,7 +4024,7 @@ App::delete('/v1/account')
     });
 
 App::post('/v1/account/targets/push')
-    ->desc('Create a push target')
+    ->desc('Create push target')
     ->groups(['api', 'account'])
     ->label('scope', 'targets.write')
     ->label('audits.event', 'target.create')
@@ -4097,7 +4097,7 @@ App::post('/v1/account/targets/push')
     });
 
 App::put('/v1/account/targets/:targetId/push')
-    ->desc('Update a push target')
+    ->desc('Update push target')
     ->groups(['api', 'account'])
     ->label('scope', 'targets.write')
     ->label('audits.event', 'target.update')
@@ -4152,7 +4152,7 @@ App::put('/v1/account/targets/:targetId/push')
     });
 
 App::delete('/v1/account/targets/:targetId/push')
-    ->desc('Delete a push target')
+    ->desc('Delete push target')
     ->groups(['api', 'account'])
     ->label('scope', 'targets.write')
     ->label('audits.event', 'target.delete')

app/controllers/api/databases.php

@@ -3635,7 +3635,7 @@ App::delete('/v1/databases/:databaseId/collections/:collectionId/documents/:docu
     });
 
 App::get('/v1/databases/usage')
-    ->desc('Get usage stats for the database')
+    ->desc('Get databases usage stats')
     ->groups(['api', 'database', 'usage'])
     ->label('scope', 'collections.read')
     ->label('sdk.auth', [APP_AUTH_TYPE_ADMIN])
@@ -3713,7 +3713,7 @@ App::get('/v1/databases/usage')
     });
 
 App::get('/v1/databases/:databaseId/usage')
-    ->desc('Get usage stats for the database')
+    ->desc('Get database usage stats')
     ->groups(['api', 'database', 'usage'])
     ->label('scope', 'collections.read')
     ->label('sdk.auth', [APP_AUTH_TYPE_ADMIN])
@@ -3797,7 +3797,7 @@ App::get('/v1/databases/:databaseId/usage')
 
 App::get('/v1/databases/:databaseId/collections/:collectionId/usage')
     ->alias('/v1/database/:collectionId/usage', ['databaseId' => 'default'])
-    ->desc('Get usage stats for a collection')
+    ->desc('Get collection usage stats')
     ->groups(['api', 'database', 'usage'])
     ->label('scope', 'collections.read')
     ->label('sdk.auth', [APP_AUTH_TYPE_ADMIN])

app/controllers/api/messaging.php

@@ -145,7 +145,7 @@ App::post('/v1/messaging/providers/sendgrid')
     ->label('sdk.auth', [APP_AUTH_TYPE_ADMIN, APP_AUTH_TYPE_KEY])
     ->label('sdk.namespace', 'messaging')
     ->label('sdk.method', 'createSendgridProvider')
-    ->label('sdk.description', '/docs/references/messaging/create-sengrid-provider.md')
+    ->label('sdk.description', '/docs/references/messaging/create-sendgrid-provider.md')
     ->label('sdk.response.code', Response::STATUS_CODE_CREATED)
     ->label('sdk.response.type', Response::CONTENT_TYPE_JSON)
     ->label('sdk.response.model', Response::MODEL_PROVIDER)
@@ -1924,7 +1924,7 @@ App::delete('/v1/messaging/providers/:providerId')
     });
 
 App::post('/v1/messaging/topics')
-    ->desc('Create a topic')
+    ->desc('Create topic')
     ->groups(['api', 'messaging'])
     ->label('audits.event', 'topic.create')
     ->label('audits.resource', 'topic/{response.$id}')
@@ -2107,7 +2107,7 @@ App::get('/v1/messaging/topics/:topicId/logs')
     });
 
 App::get('/v1/messaging/topics/:topicId')
-    ->desc('Get a topic')
+    ->desc('Get topic')
     ->groups(['api', 'messaging'])
     ->label('scope', 'topics.read')
     ->label('sdk.auth', [APP_AUTH_TYPE_ADMIN, APP_AUTH_TYPE_KEY])
@@ -2134,7 +2134,7 @@ App::get('/v1/messaging/topics/:topicId')
     });
 
 App::patch('/v1/messaging/topics/:topicId')
-    ->desc('Update a topic')
+    ->desc('Update topic')
     ->groups(['api', 'messaging'])
     ->label('audits.event', 'topic.update')
     ->label('audits.resource', 'topic/{response.$id}')
@@ -2178,7 +2178,7 @@ App::patch('/v1/messaging/topics/:topicId')
     });
 
 App::delete('/v1/messaging/topics/:topicId')
-    ->desc('Delete a topic')
+    ->desc('Delete topic')
     ->groups(['api', 'messaging'])
     ->label('audits.event', 'topic.delete')
     ->label('audits.resource', 'topic/{request.$topicId}')
@@ -2218,7 +2218,7 @@ App::delete('/v1/messaging/topics/:topicId')
     });
 
 App::post('/v1/messaging/topics/:topicId/subscribers')
-    ->desc('Create a subscriber')
+    ->desc('Create subscriber')
     ->groups(['api', 'messaging'])
     ->label('audits.event', 'subscriber.create')
     ->label('audits.resource', 'subscriber/{response.$id}')
@@ -2477,7 +2477,7 @@ App::get('/v1/messaging/subscribers/:subscriberId/logs')
     });
 
 App::get('/v1/messaging/topics/:topicId/subscribers/:subscriberId')
-    ->desc('Get a subscriber')
+    ->desc('Get subscriber')
     ->groups(['api', 'messaging'])
     ->label('scope', 'subscribers.read')
     ->label('sdk.auth', [APP_AUTH_TYPE_ADMIN, APP_AUTH_TYPE_KEY])
@@ -2516,7 +2516,7 @@ App::get('/v1/messaging/topics/:topicId/subscribers/:subscriberId')
     });
 
 App::delete('/v1/messaging/topics/:topicId/subscribers/:subscriberId')
-    ->desc('Delete a subscriber')
+    ->desc('Delete subscriber')
     ->groups(['api', 'messaging'])
     ->label('audits.event', 'subscriber.delete')
     ->label('audits.resource', 'subscriber/{request.$subscriberId}')
@@ -2575,7 +2575,7 @@ App::delete('/v1/messaging/topics/:topicId/subscribers/:subscriberId')
     });
 
 App::post('/v1/messaging/messages/email')
-    ->desc('Create an email')
+    ->desc('Create email')
     ->groups(['api', 'messaging'])
     ->label('audits.event', 'message.create')
     ->label('audits.resource', 'message/{response.$id}')
@@ -2719,7 +2719,7 @@ App::post('/v1/messaging/messages/email')
     });
 
 App::post('/v1/messaging/messages/sms')
-    ->desc('Create an SMS')
+    ->desc('Create SMS')
     ->groups(['api', 'messaging'])
     ->label('audits.event', 'message.create')
     ->label('audits.resource', 'message/{response.$id}')
@@ -2827,7 +2827,7 @@ App::post('/v1/messaging/messages/sms')
     });
 
 App::post('/v1/messaging/messages/push')
-    ->desc('Create a push notification')
+    ->desc('Create push notification')
     ->groups(['api', 'messaging'])
     ->label('audits.event', 'message.create')
     ->label('audits.resource', 'message/{response.$id}')
@@ -3190,7 +3190,7 @@ App::get('/v1/messaging/messages/:messageId/targets')
     });
 
 App::get('/v1/messaging/messages/:messageId')
-    ->desc('Get a message')
+    ->desc('Get message')
     ->groups(['api', 'messaging'])
     ->label('scope', 'messages.read')
     ->label('sdk.auth', [APP_AUTH_TYPE_ADMIN, APP_AUTH_TYPE_KEY])
@@ -3214,7 +3214,7 @@ App::get('/v1/messaging/messages/:messageId')
     });
 
 App::patch('/v1/messaging/messages/email/:messageId')
-    ->desc('Update an email')
+    ->desc('Update email')
     ->groups(['api', 'messaging'])
     ->label('audits.event', 'message.update')
     ->label('audits.resource', 'message/{response.$id}')
@@ -3352,7 +3352,7 @@ App::patch('/v1/messaging/messages/email/:messageId')
     });
 
 App::patch('/v1/messaging/messages/sms/:messageId')
-    ->desc('Update an SMS')
+    ->desc('Update SMS')
     ->groups(['api', 'messaging'])
     ->label('audits.event', 'message.update')
     ->label('audits.resource', 'message/{response.$id}')
@@ -3470,7 +3470,7 @@ App::patch('/v1/messaging/messages/sms/:messageId')
     });
 
 App::patch('/v1/messaging/messages/push/:messageId')
-    ->desc('Update a push notification')
+    ->desc('Update push notification')
     ->groups(['api', 'messaging'])
     ->label('audits.event', 'message.update')
     ->label('audits.resource', 'message/{response.$id}')
@@ -3661,7 +3661,7 @@ App::patch('/v1/messaging/messages/push/:messageId')
     });
 
 App::delete('/v1/messaging/messages/:messageId')
-    ->desc('Delete a message')
+    ->desc('Delete message')
     ->groups(['api', 'messaging'])
     ->label('audits.event', 'message.delete')
     ->label('audits.resource', 'message/{request.route.messageId}')

app/controllers/api/migrations.php

@@ -1038,7 +1038,7 @@ App::delete('/v1/migrations/:migrationId')
     ->label('sdk.auth', [APP_AUTH_TYPE_ADMIN])
     ->label('sdk.namespace', 'migrations')
     ->label('sdk.method', 'delete')
-    ->label('sdk.description', '/docs/references/functions/delete-migration.md')
+    ->label('sdk.description', '/docs/references/migrations/delete-migration.md')
     ->label('sdk.response.code', Response::STATUS_CODE_NOCONTENT)
     ->label('sdk.response.model', Response::MODEL_NONE)
     ->param('migrationId', '', new UID(), 'Migration ID.')

app/controllers/api/project.php

@@ -18,7 +18,7 @@ use Utopia\Validator\Text;
 use Utopia\Validator\WhiteList;
 
 App::get('/v1/project/usage')
-    ->desc('Get usage stats for a project')
+    ->desc('Get project usage stats')
     ->groups(['api', 'usage'])
     ->label('scope', 'projects.read')
     ->label('sdk.auth', [APP_AUTH_TYPE_ADMIN])

app/controllers/api/storage.php

@@ -1514,7 +1514,7 @@ App::delete('/v1/storage/buckets/:bucketId/files/:fileId')
     });
 
 App::get('/v1/storage/usage')
-    ->desc('Get usage stats for storage')
+    ->desc('Get storage usage stats')
     ->groups(['api', 'storage'])
     ->label('scope', 'files.read')
     ->label('sdk.auth', [APP_AUTH_TYPE_ADMIN])
@@ -1593,7 +1593,7 @@ App::get('/v1/storage/usage')
     });
 
 App::get('/v1/storage/:bucketId/usage')
-    ->desc('Get usage stats for storage bucket')
+    ->desc('Get bucket usage stats')
     ->groups(['api', 'storage'])
     ->label('scope', 'files.read')
     ->label('sdk.auth', [APP_AUTH_TYPE_ADMIN])

app/controllers/api/users.php

@@ -1968,7 +1968,7 @@ App::delete('/v1/users/identities/:identityId')
     });
 
 App::get('/v1/users/usage')
-    ->desc('Get usage stats for the users API')
+    ->desc('Get users usage stats')
     ->groups(['api', 'users'])
     ->label('scope', 'users.read')
     ->label('sdk.auth', [APP_AUTH_TYPE_ADMIN])

docs/references/account/add-authenticator.md

@@ -0,0 +1 @@
+Add an authenticator app to be used as an MFA factor. Verify the authenticator using the [verify authenticator](/docs/references/cloud/client-web/account#verifyAuthenticator) method.

docs/references/account/create-2fa-challenge.md

@@ -0,0 +1 @@
+Initialize an MFA challenge of the specified factor. The factor must be available on the account.

docs/references/account/delete-mfa.md

@@ -0,0 +1 @@
+Delete an authenticator for a user by ID.

docs/references/account/list-factors.md

@@ -0,0 +1 @@
+List the factors available on the account to be used as a MFA challange.

docs/references/account/update-challenge.md

@@ -0,0 +1 @@
+Complete the MFA challenge by providing the one-time password.

docs/references/account/update-mfa.md

@@ -0,0 +1 @@
+Enable or disable MFA on an account.

docs/references/account/verify-authenticator.md

@@ -0,0 +1 @@
+Verify an authenticator app after adding it using the [add authenticator](/docs/references/cloud/client-web/account#addAuthenticator) method.

docs/references/databases/create-attribute-enum.md

@@ -0,0 +1 @@
+Create an enumeration attribute. The `elements` param acts as a white-list of accepted values for this attribute. 

docs/references/databases/create-datetime-attribute.md

@@ -0,0 +1 @@
+Create a date time attribute according to the ISO 8601 standard.

docs/references/databases/create-index.md

@@ -0,0 +1,2 @@
+Creates an index on the attributes listed. Your index should include all the attributes you will query in a single request.
+Attributes can be `key`, `fulltext`, and `unique`.

docs/references/databases/delete-attribute.md

@@ -0,0 +1 @@
+Deletes an attribute.

docs/references/databases/delete-index.md

@@ -0,0 +1 @@
+Delete an index.

docs/references/databases/get-attribute.md

@@ -0,0 +1 @@
+Get attribute by ID.

docs/references/databases/get-index.md

@@ -0,0 +1 @@
+Get index by ID.

docs/references/databases/list-attributes.md

@@ -0,0 +1 @@
+List attributes in the collection.

docs/references/databases/list-indexes.md

@@ -0,0 +1 @@
+List indexes in the collection.

docs/references/databases/update-boolean-attribute.md

@@ -0,0 +1 @@
+Update a boolean attribute. Changing the `default` value will not update already existing documents.

docs/references/databases/update-datetime-attribute.md

@@ -0,0 +1 @@
+Update a date time attribute. Changing the `default` value will not update already existing documents.

docs/references/health/get-queue-functions.md

@@ -0,0 +1 @@
+Get the number of function executions that are waiting to be processed in the Appwrite internal queue server.

docs/references/messaging/delete-message.md

@@ -0,0 +1 @@
+Delete a message. If the message is not a draft or scheduled, but has been sent, this will not recall the message.

docs/references/users/create-target.md

@@ -0,0 +1 @@
+Create a messaging target.

docs/references/users/delete-mfa.md

@@ -0,0 +1 @@
+Delete an authenticator app.

docs/references/users/delete-target.md

@@ -0,0 +1 @@
+Delete a messaging target.

docs/references/users/get-user-target.md

@@ -0,0 +1 @@
+Get a user's push notification target by ID.

docs/references/users/list-factors.md

@@ -0,0 +1 @@
+List the factors available on the account to be used as a MFA challange.

docs/references/users/list-user-targets.md

@@ -0,0 +1 @@
+List the messaging targets that are associated with a user.

docs/references/users/update-target.md

@@ -0,0 +1 @@
+Update a messaging target.

docs/references/users/update-user-mfa.md

@@ -0,0 +1 @@
+Enable or disable MFA on a user account.