From d24cf0d9a0327ef66c4560ac6197258a893a1ae0 Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Fri, 9 Jun 2023 21:04:36 +0000 Subject: [PATCH] Rest improvements in docs --- app/views/docs/rest.phtml | 38 ++++++++++++++++++++++++-------------- 1 file changed, 24 insertions(+), 14 deletions(-) diff --git a/app/views/docs/rest.phtml b/app/views/docs/rest.phtml index 882db5e6b..979b0fd59 100644 --- a/app/views/docs/rest.phtml +++ b/app/views/docs/rest.phtml @@ -2,7 +2,7 @@

The REST API allows you to access your Appwrite server through HTTP requests without the needing an SDK. Each endpoint in the API represents a specific operation on a specific resource.

-

Headers

+

Headers

Appwrite's REST APIs expect certain headers to be included with each request:

@@ -47,13 +47,13 @@
-

Using Appwrite Without Headers

+

Using Appwrite Without Headers

Some use cases do not allow custom headers, such as embedding images from Appwrite in HTML. In these cases, you can provide the Appwrite project ID using the query parameter project.

'); ?>
-

Client Authentication

+

Client Authentication

You can create account sessions with POST requests to the Account API. Sessions are persisted using secured cookies. You can learn more about session persistence in the Authentication Guide.

The example below shows creating an account session with the Create Account Session with Email endpoint.

@@ -81,7 +81,7 @@ Content-Type: application/json X-Appwrite-Project: [PROJECT_ID]
-

Server Authentication

+

Server Authentication

Server integrations use API keys to authenticate and are typically used for backend applications.

Server APIs are authenticated with API keys instead of account sessions. Simply pass an API key in the X-Appwrite-key: [API-KEY] header with the appropriate scopes.

@@ -92,7 +92,7 @@ X-Appwrite-Project: [PROJECT_ID] X-Appwrite-Key: [API_KEY] -

JWT Authentication

+

JWT Authentication

JWT authentication is frequently used by server applications to act on behalf of a user. Users generate tokens using the Create JWT endpoint. When issuing requests authenticated with a JWT, Appwrite will treat the request like it is from the authenticated user.

@@ -102,7 +102,7 @@ X-Appwrite-Project: [PROJECT_ID] X-Appwrite-JWT: [TOKEN]
-

File Handling

+

File Handling

Appwrite implements resumable, chunked uploads for files larger than 5MB. Chunked uploads send files in chunks of 5MB to reduce memory footprint and increase resilience when handling large files. Appwrite SDKs will automatically handle chunked uploads, but it is possible to implement this with the REST API directly.

Upload endpoints in Appwrite, such as Create File and Create Deployment, are different from other endpoints. These endpoints take multipart form data instead of JSON data. To implement chunked uploads, you will need to implement the following headers:

@@ -208,7 +208,7 @@ read("user:627a958ded6424a98a9f") ------WebKitFormBoundarye0m6iNBQNHlzTpVM-- -

Permissions

+

Permissions

Appwrite SDKs have helpers to generate permission strings, but when using Appwrite without SDKs, you'd need to create the strings yourself.

@@ -294,17 +294,17 @@ read("user:627a958ded6424a98a9f") - +

-

Unique ID

+

Unique ID

Appwrite's SDKs have a helper ID.unique() to generate unique IDs. When using Appwrite without an SDK, pass the string "unique()" into the ID parameter.

-

Query Methods

+

Query Methods

Appwrite's SDKs provide a Query class to generate query strings. When using Appwrite without an SDK, you can template your own strings with the format below. @@ -403,13 +403,23 @@ Appwrite's SDKs provide a Query class to generate query strings. Wh

Best Practice

When using greater than, greater than or equal to, less than, or less than or equal to, it is not recommended to pass in multiple values. While the API will accept multiple values and return results with or logic, it's best practice to pass in only one value for performance reasons.

+

Rate Limits

+

Appwrite's REST APIs are protected by the same rate limit policies, just like when using SDKs. Each API has a different rate limit, which is documented in the References section of each service in the Appwrite documentation.

+ +

+

  • Learn more about Rate Limits
    • +

    + +

    Stateless

    +

    Appwrite's REST APIs are stateless. Each time you make a request, Appwrite receives all the information it needs to perform the action, regardless of what requests you make before and after that request.

    +

    Since each requests is stateless, they can be handled in any given order when sent concurrently, as long as they don't make conflicting changes to the same resource.

    -

    OpenAPI and Swagger Specs

    +

    OpenAPI and Swagger Specs

    Appwrite provides a full REST API specification in the OpenAPI 3 and Swagger 2 formats every release. These can be accessed through Appwrite's GitHub repository and rendered using a variety of parsers and tools.

    - +