Appwrite/appwrite
1
0
Fork 0
mirror of https://github.com/appwrite/appwrite.git synced 2026-05-26 13:51:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #10204 from appwrite/add-docs-swift-apple

Browse Source 
chore: add docs for nestedType, encode, from and toMap
This commit is contained in:
Luke B. Silver
2025-07-27 12:55:21 +01:00
committed by GitHub
parent 1f13a0d437 3c6291024b
commit 1d736dec54
12 changed files with 598 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sdks/android/GETTING_STARTED.md
+127
View File
@@ -79,7 +79,134 @@ val user = account.create(
)
```
### Type Safety with Models
The Appwrite Android SDK provides type safety when working with database documents through generic methods. Methods like `listDocuments`, `getDocument`, and others accept a `nestedType` parameter that allows you to specify your custom model type for full type safety.
**Kotlin:**
```kotlin
data class Book(
val name: String,
val author: String,
val releaseYear: String? = null,
val category: String? = null,
val genre: List<String>? = null,
val isCheckedOut: Boolean
)
val databases = Databases(client)
try {
val documents = databases.listDocuments(
databaseId = "your-database-id",
collectionId = "your-collection-id",
nestedType = Book::class.java // Pass in your custom model type
)
for (book in documents.documents) {
Log.d("Appwrite", "Book: ${book.name} by ${book.author}") // Now you have full type safety
}
} catch (e: AppwriteException) {
Log.e("Appwrite", e.message ?: "Unknown error")
}
```
**Java:**
```java
public class Book {
private String name;
private String author;
private String releaseYear;
private String category;
private List<String> genre;
private boolean isCheckedOut;
// Constructor
public Book(String name, String author, boolean isCheckedOut) {
this.name = name;
this.author = author;
this.isCheckedOut = isCheckedOut;
}
// Getters and setters
public String getName() { return name; }
public void setName(String name) { this.name = name; }
public String getAuthor() { return author; }
public void setAuthor(String author) { this.author = author; }
public String getReleaseYear() { return releaseYear; }
public void setReleaseYear(String releaseYear) { this.releaseYear = releaseYear; }
public String getCategory() { return category; }
public void setCategory(String category) { this.category = category; }
public List<String> getGenre() { return genre; }
public void setGenre(List<String> genre) { this.genre = genre; }
public boolean isCheckedOut() { return isCheckedOut; }
public void setCheckedOut(boolean checkedOut) { isCheckedOut = checkedOut; }
}
Databases databases = new Databases(client);
try {
DocumentList<Book> documents = databases.listDocuments(
"your-database-id",
"your-collection-id",
Book.class // Pass in your custom model type
);
for (Book book : documents.getDocuments()) {
Log.d("Appwrite", "Book: " + book.getName() + " by " + book.getAuthor()); // Now you have full type safety
}
} catch (AppwriteException e) {
Log.e("Appwrite", e.getMessage() != null ? e.getMessage() : "Unknown error");
}
```
**Tip**: You can use the `appwrite types` command to automatically generate model definitions based on your Appwrite database schema. Learn more about [type generation](https://appwrite.io/docs/products/databases/type-generation).
### Working with Model Methods
All Appwrite models come with built-in methods for data conversion and manipulation:
**`toMap()`** - Converts a model instance to a Map format, useful for debugging or manual data manipulation:
```kotlin
val account = Account(client)
val user = account.get()
val userMap = user.toMap()
Log.d("Appwrite", userMap.toString()) // Prints all user properties as a Map
```
**`from(map:, nestedType:)`** - Creates a model instance from a Map, useful when working with raw data:
```kotlin
val userData: Map<String, Any> = mapOf(
"\$id" to "123",
"name" to "John",
"email" to "john@example.com"
)
val user = User.from(userData, User::class.java)
```
**JSON Serialization** - Models can be easily converted to/from JSON using Gson (which the SDK uses internally):
```kotlin
import com.google.gson.Gson
val account = Account(client)
val user = account.get()
// Convert to JSON
val gson = Gson()
val jsonString = gson.toJson(user)
Log.d("Appwrite", "User JSON: $jsonString")
// Convert from JSON
val userFromJson = gson.fromJson(jsonString, User::class.java)
```
### Error Handling
The Appwrite Android SDK raises an `AppwriteException` object with `message`, `code` and `response` properties. You can handle any errors by catching `AppwriteException` and present the `message` to the user or handle it yourself based on the provided error information. Below is an example.
```kotlin
docs/sdks/apple/GETTING_STARTED.md
+57
View File
@@ -113,6 +113,63 @@ func main() {
}
```
### Type Safety with Models
The Appwrite Apple SDK provides type safety when working with database documents through generic methods. Methods like `listDocuments`, `getDocument`, and others accept a `nestedType` parameter that allows you to specify your custom model type for full type safety.
```swift
struct Book: Codable {
let name: String
let author: String
let releaseYear: String?
let category: String?
let genre: [String]?
let isCheckedOut: Bool
}
let databases = Databases(client)
do {
let documents = try await databases.listDocuments(
databaseId: "your-database-id",
collectionId: "your-collection-id",
nestedType: Book.self // Pass in your custom model type
)
for book in documents.documents {
print("Book: \(book.name) by \(book.author)") // Now you have full type safety
}
} catch {
print(error.localizedDescription)
}
```
**Tip**: You can use the `appwrite types` command to automatically generate model definitions based on your Appwrite database schema. Learn more about [type generation](https://appwrite.io/docs/products/databases/type-generation).
### Working with Model Methods
All Appwrite models come with built-in methods for data conversion and manipulation:
**`toMap()`** - Converts a model instance to a dictionary format, useful for debugging or manual data manipulation:
```swift
let user = try await account.get()
let userMap = user.toMap()
print(userMap) // Prints all user properties as a dictionary
```
**`from(map:)`** - Creates a model instance from a dictionary, useful when working with raw data:
```swift
let userData: [String: Any] = ["$id": "123", "name": "John", "email": "john@example.com"]
let user = User.from(map: userData)
```
**`encode(to:)`** - Encodes the model to JSON format (part of Swift's Codable protocol), useful for serialization:
```swift
let user = try await account.get()
let jsonData = try JSONEncoder().encode(user)
let jsonString = String(data: jsonData, encoding: .utf8)
```
### Error Handling
When an error occurs, the Appwrite Apple SDK throws an `AppwriteError` object with `message` and `code` properties. You can handle any errors in a catch block and present the `message` or `localizedDescription` to the user or handle it yourself based on the provided error information. Below is an example.
docs/sdks/dart/EXAMPLES.md
-62
View File
@@ -1,62 +0,0 @@
# Examples
Init your Appwrite client:
```dart
Client client = Client();
client
.setEndpoint('https://localhost/v1') // Your Appwrite Endpoint
.setProject('5e8cf4f46b5e8') // Your project ID
.setSelfSigned() // Remove in production
;
```
Create a new user:
```dart
Users users = Users(client);
User result = await users.create(
userId: ID.unique(),
email: "email@example.com",
phone: "+123456789",
password: "password",
name: "Walter O'Brien"
);
```
Fetch user profile:
```dart
Users users = Users(client);
User profile = await users.get(
userId: '[USER_ID]',
);
```
Upload File:
```dart
Storage storage = Storage(client);
InputFile file = InputFile(path: './path-to-file/image.jpg', filename: 'image.jpg');
storage.createFile(
bucketId: '[BUCKET_ID]',
fileId: '[FILE_ID]', // use 'unique()' to automatically generate a unique ID
file: file,
permissions: [
Permission.read(Role.any()),
],
)
.then((response) {
print(response); // File uploaded!
})
.catchError((error) {
print(error.response);
});
```
All examples and API features are available at the [official Appwrite docs](https://appwrite.io/docs)
docs/sdks/deno/GETTING_STARTED.md
+4
View File
@@ -1,6 +1,7 @@
## Getting Started
### Init your SDK
Initialize your SDK with your Appwrite server API endpoint and project ID which can be found in your project settings page and your new API secret Key from project's API keys section.
```typescript
@@ -26,6 +27,7 @@ console.log(user);
```
### Full Example
```typescript
import * as sdk from "https://deno.land/x/appwrite/mod.ts";
@@ -44,6 +46,7 @@ console.log(user);
```
### Error Handling
The Appwrite Deno SDK raises `AppwriteException` object with `message`, `code` and `response` properties. You can handle any errors by catching `AppwriteException` and present the `message` to the user or handle it yourself based on the provided error information. Below is an example.
```typescript
@@ -57,6 +60,7 @@ try {
```
### Learn more
You can use the following resources to learn more and get help
- 🚀 [Getting Started Tutorial](https://appwrite.io/docs/getting-started-for-server)
- 📜 [Appwrite Docs](https://appwrite.io/docs)
docs/sdks/java/CHANGELOG.md
-1
View File
@@ -1 +0,0 @@
# Change Log
docs/sdks/kotlin/GETTING_STARTED.md
+126
View File
@@ -57,6 +57,132 @@ suspend fun main() {
}
```
### Type Safety with Models
The Appwrite Kotlin SDK provides type safety when working with database documents through generic methods. Methods like `listDocuments`, `getDocument`, and others accept a `nestedType` parameter that allows you to specify your custom model type for full type safety.
**Kotlin:**
```kotlin
data class Book(
val name: String,
val author: String,
val releaseYear: String? = null,
val category: String? = null,
val genre: List<String>? = null,
val isCheckedOut: Boolean
)
val databases = Databases(client)
try {
val documents = databases.listDocuments(
databaseId = "your-database-id",
collectionId = "your-collection-id",
nestedType = Book::class.java // Pass in your custom model type
)
for (book in documents.documents) {
Log.d("Appwrite", "Book: ${book.name} by ${book.author}") // Now you have full type safety
}
} catch (e: AppwriteException) {
Log.e("Appwrite", e.message ?: "Unknown error")
}
```
**Java:**
```java
public class Book {
private String name;
private String author;
private String releaseYear;
private String category;
private List<String> genre;
private boolean isCheckedOut;
// Constructor
public Book(String name, String author, boolean isCheckedOut) {
this.name = name;
this.author = author;
this.isCheckedOut = isCheckedOut;
}
// Getters and setters
public String getName() { return name; }
public void setName(String name) { this.name = name; }
public String getAuthor() { return author; }
public void setAuthor(String author) { this.author = author; }
public String getReleaseYear() { return releaseYear; }
public void setReleaseYear(String releaseYear) { this.releaseYear = releaseYear; }
public String getCategory() { return category; }
public void setCategory(String category) { this.category = category; }
public List<String> getGenre() { return genre; }
public void setGenre(List<String> genre) { this.genre = genre; }
public boolean isCheckedOut() { return isCheckedOut; }
public void setCheckedOut(boolean checkedOut) { isCheckedOut = checkedOut; }
}
Databases databases = new Databases(client);
try {
DocumentList<Book> documents = databases.listDocuments(
"your-database-id",
"your-collection-id",
Book.class // Pass in your custom model type
);
for (Book book : documents.getDocuments()) {
Log.d("Appwrite", "Book: " + book.getName() + " by " + book.getAuthor()); // Now you have full type safety
}
} catch (AppwriteException e) {
Log.e("Appwrite", e.getMessage() != null ? e.getMessage() : "Unknown error");
}
```
**Tip**: You can use the `appwrite types` command to automatically generate model definitions based on your Appwrite database schema. Learn more about [type generation](https://appwrite.io/docs/products/databases/type-generation).
### Working with Model Methods
All Appwrite models come with built-in methods for data conversion and manipulation:
**`toMap()`** - Converts a model instance to a Map format, useful for debugging or manual data manipulation:
```kotlin
val account = Account(client)
val user = account.get()
val userMap = user.toMap()
Log.d("Appwrite", userMap.toString()) // Prints all user properties as a Map
```
**`from(map:, nestedType:)`** - Creates a model instance from a Map, useful when working with raw data:
```kotlin
val userData: Map<String, Any> = mapOf(
"\$id" to "123",
"name" to "John",
"email" to "john@example.com"
)
val user = User.from(userData, User::class.java)
```
**JSON Serialization** - Models can be easily converted to/from JSON using Gson (which the SDK uses internally):
```kotlin
import com.google.gson.Gson
val account = Account(client)
val user = account.get()
// Convert to JSON
val gson = Gson()
val jsonString = gson.toJson(user)
Log.d("Appwrite", "User JSON: $jsonString")
// Convert from JSON
val userFromJson = gson.fromJson(jsonString, User::class.java)
```
### Error Handling
The Appwrite Kotlin SDK raises `AppwriteException` object with `message`, `code` and `response` properties. You can handle any errors by catching `AppwriteException` and present the `message` to the user or handle it yourself based on the provided error information. Below is an example.
docs/sdks/nodejs/GETTING_STARTED.md
+65
View File
@@ -1,6 +1,7 @@
## Getting Started
### Init your SDK
Initialize your SDK with your Appwrite server API endpoint and project ID which can be found in your project settings page and your new API secret Key project API keys section.
```js
@@ -17,6 +18,7 @@ client
```
### Make Your First Request
Once your SDK object is set, create any of the Appwrite service objects and choose any request to send. Full documentation for any service method you would like to use can be found in your SDK documentation or in the [API References](https://appwrite.io/docs) section.
```js
@@ -54,7 +56,70 @@ promise.then(function (response) {
});
```
### Type Safety with Models
The Appwrite Node SDK provides type safety when working with database documents through generic methods. Methods like `listDocuments`, `getDocument`, and others accept a generic type parameter that allows you to specify your custom model type for full type safety.
**TypeScript:**
```typescript
interface Book {
name: string;
author: string;
releaseYear?: string;
category?: string;
genre?: string[];
isCheckedOut: boolean;
}
const databases = new Databases(client);
try {
const documents = await databases.listDocuments<Book>(
'your-database-id',
'your-collection-id'
);
documents.documents.forEach(book => {
console.log(`Book: ${book.name} by ${book.author}`); // Now you have full type safety
});
} catch (error) {
console.error('Appwrite error:', error);
}
```
**JavaScript (with JSDoc for type hints):**
```javascript
/**
* @typedef {Object} Book
* @property {string} name
* @property {string} author
* @property {string} [releaseYear]
* @property {string} [category]
* @property {string[]} [genre]
* @property {boolean} isCheckedOut
*/
const databases = new Databases(client);
try {
/** @type {Models.DocumentList<Book>} */
const documents = await databases.listDocuments(
'your-database-id',
'your-collection-id'
);
documents.documents.forEach(book => {
console.log(`Book: ${book.name} by ${book.author}`); // Type hints available in IDE
});
} catch (error) {
console.error('Appwrite error:', error);
}
```
**Tip**: You can use the `appwrite types` command to automatically generate TypeScript interfaces based on your Appwrite database schema. Learn more about [type generation](https://appwrite.io/docs/products/databases/type-generation).
### Error Handling
The Appwrite Node SDK raises `AppwriteException` object with `message`, `code` and `response` properties. You can handle any errors by catching `AppwriteException` and present the `message` to the user or handle it yourself based on the provided error information. Below is an example.
```js
docs/sdks/react-native/GETTING_STARTED.md
+82 -2
View File
@@ -1,12 +1,13 @@
## Getting Started
### Add your Platform
If this is your first time using Appwrite, create an account and create your first project.
Then, under **Add a platform**, add a **Android app** or a **Apple app**. You can skip optional steps.
#### iOS steps
Add your app **name** and **Bundle ID**. You can find your **Bundle Identifier** in the **General** tab for your app's primary target in XCode. For Expo projects you can set or find it on **app.json** file at your project's root directory.
#### Android steps
@@ -24,6 +25,7 @@ import 'react-native-url-polyfill/auto'
> `cd ios && pod install && cd ..`
### Init your SDK
Initialize your SDK with your Appwrite server API endpoint and project ID which can be found in your project settings page.
```js
@@ -39,6 +41,7 @@ client
```
### Make Your First Request
Once your SDK object is set, access any of the Appwrite services and choose any request to send. Full documentation for any service method you would like to use can be found in your SDK documentation or in the [API References](https://appwrite.io/docs) section.
```js
@@ -55,6 +58,7 @@ account.create(ID.unique(), 'me@example.com', 'password', 'Jane Doe')
```
### Full Example
```js
import { Client, Account } from 'react-native-appwrite';
// Init your React Native SDK
@@ -77,9 +81,85 @@ account.create(ID.unique(), 'me@example.com', 'password', 'Jane Doe')
});
```
### Type Safety with Models
The Appwrite React Native SDK provides type safety when working with database documents through generic methods. Methods like `listDocuments`, `getDocument`, and others accept a generic type parameter that allows you to specify your custom model type for full type safety.
**TypeScript:**
```typescript
interface Book {
name: string;
author: string;
releaseYear?: string;
category?: string;
genre?: string[];
isCheckedOut: boolean;
}
const databases = new Databases(client);
try {
const documents = await databases.listDocuments<Book>(
'your-database-id',
'your-collection-id'
);
documents.documents.forEach(book => {
console.log(`Book: ${book.name} by ${book.author}`); // Now you have full type safety
});
} catch (error) {
console.error('Appwrite error:', error);
}
```
**JavaScript (with JSDoc for type hints):**
```javascript
/**
* @typedef {Object} Book
* @property {string} name
* @property {string} author
* @property {string} [releaseYear]
* @property {string} [category]
* @property {string[]} [genre]
* @property {boolean} isCheckedOut
*/
const databases = new Databases(client);
try {
/** @type {Models.DocumentList<Book>} */
const documents = await databases.listDocuments(
'your-database-id',
'your-collection-id'
);
documents.documents.forEach(book => {
console.log(`Book: ${book.name} by ${book.author}`); // Type hints available in IDE
});
} catch (error) {
console.error('Appwrite error:', error);
}
```
**Tip**: You can use the `appwrite types` command to automatically generate TypeScript interfaces based on your Appwrite database schema. Learn more about [type generation](https://appwrite.io/docs/products/databases/type-generation).
### Error Handling
The Appwrite React Native SDK raises an `AppwriteException` object with `message`, `code` and `response` properties. You can handle any errors by catching the exception and present the `message` to the user or handle it yourself based on the provided error information. Below is an example.
```javascript
try {
const user = await account.create(ID.unique(), "email@example.com", "password", "Walter O'Brien");
console.log('User created:', user);
} catch (error) {
console.error('Appwrite error:', error.message);
}
```
### Learn more
You can use the following resources to learn more and get help
- 🚀 [Getting Started Tutorial](https://appwrite.io/docs/quick-starts/react-native)
- 📜 [Appwrite Docs](https://appwrite.io/docs)
- 💬 [Discord Community](https://appwrite.io/discord)
- 🚂 [Appwrite React Native Playground](https://github.com/appwrite/playground-for-react-native)
- 🚂 [Appwrite React Native Playground](https://github.com/appwrite/playground-for-react-native)
docs/sdks/swift/GETTING_STARTED.md
+57
View File
@@ -66,6 +66,63 @@ func main() {
}
```
### Type Safety with Models
The Appwrite Swift SDK provides type safety when working with database documents through generic methods. Methods like `listDocuments`, `getDocument`, and others accept a `nestedType` parameter that allows you to specify your custom model type for full type safety.
```swift
struct Book: Codable {
let name: String
let author: String
let releaseYear: String?
let category: String?
let genre: [String]?
let isCheckedOut: Bool
}
let databases = Databases(client)
do {
let documents = try await databases.listDocuments(
databaseId: "your-database-id",
collectionId: "your-collection-id",
nestedType: Book.self // Pass in your custom model type
)
for book in documents.documents {
print("Book: \(book.name) by \(book.author)") // Now you have full type safety
}
} catch {
print(error.localizedDescription)
}
```
**Tip**: You can use the `appwrite types` command to automatically generate model definitions based on your Appwrite database schema. Learn more about [type generation](https://appwrite.io/docs/products/databases/type-generation).
### Working with Model Methods
All Appwrite models come with built-in methods for data conversion and manipulation:
**`toMap()`** - Converts a model instance to a dictionary format, useful for debugging or manual data manipulation:
```swift
let user = try await account.get()
let userMap = user.toMap()
print(userMap) // Prints all user properties as a dictionary
```
**`from(map:)`** - Creates a model instance from a dictionary, useful when working with raw data:
```swift
let userData: [String: Any] = ["$id": "123", "name": "John", "email": "john@example.com"]
let user = User.from(map: userData)
```
**`encode(to:)`** - Encodes the model to JSON format (part of Swift's Codable protocol), useful for serialization:
```swift
let user = try await account.get()
let jsonData = try JSONEncoder().encode(user)
let jsonString = String(data: jsonData, encoding: .utf8)
```
### Error Handling
When an error occurs, the Appwrite Swift SDK throws an `AppwriteError` object with `message` and `code` properties. You can handle any errors in a catch block and present the `message` or `localizedDescription` to the user or handle it yourself based on the provided error information. Below is an example.
docs/sdks/typescript/CHANGELOG.md
-1
View File
@@ -1 +0,0 @@
# Change Log
docs/sdks/web/GETTING_STARTED.md
+80
View File
@@ -1,11 +1,13 @@
## Getting Started
### Add your Web Platform
For you to init your SDK and interact with Appwrite services you need to add a web platform to your project. To add a new platform, go to your Appwrite console, choose the project you created in the step before and click the 'Add Platform' button.
From the options, choose to add a **Web** platform and add your client app hostname. By adding your hostname to your project platform you are allowing cross-domain communication between your project and the Appwrite API.
### Init your SDK
Initialize your SDK with your Appwrite server API endpoint and project ID which can be found in your project settings page.
```js
@@ -19,6 +21,7 @@ client
```
### Make Your First Request
Once your SDK object is set, access any of the Appwrite services and choose any request to send. Full documentation for any service method you would like to use can be found in your SDK documentation or in the [API References](https://appwrite.io/docs) section.
```js
@@ -35,6 +38,7 @@ account.create(ID.unique(), "email@example.com", "password", "Walter O'Brien")
```
### Full Example
```js
// Init your Web SDK
const client = new Client();
@@ -55,7 +59,83 @@ account.create(ID.unique(), "email@example.com", "password", "Walter O'Brien")
});
```
### Type Safety with Models
The Appwrite Web SDK provides type safety when working with database documents through generic methods. Methods like `listDocuments`, `getDocument`, and others accept a generic type parameter that allows you to specify your custom model type for full type safety.
**TypeScript:**
```typescript
interface Book {
name: string;
author: string;
releaseYear?: string;
category?: string;
genre?: string[];
isCheckedOut: boolean;
}
const databases = new Databases(client);
try {
const documents = await databases.listDocuments<Book>(
'your-database-id',
'your-collection-id'
);
documents.documents.forEach(book => {
console.log(`Book: ${book.name} by ${book.author}`); // Now you have full type safety
});
} catch (error) {
console.error('Appwrite error:', error);
}
```
**JavaScript (with JSDoc for type hints):**
```javascript
/**
* @typedef {Object} Book
* @property {string} name
* @property {string} author
* @property {string} [releaseYear]
* @property {string} [category]
* @property {string[]} [genre]
* @property {boolean} isCheckedOut
*/
const databases = new Databases(client);
try {
/** @type {Models.DocumentList<Book>} */
const documents = await databases.listDocuments(
'your-database-id',
'your-collection-id'
);
documents.documents.forEach(book => {
console.log(`Book: ${book.name} by ${book.author}`); // Type hints available in IDE
});
} catch (error) {
console.error('Appwrite error:', error);
}
```
**Tip**: You can use the `appwrite types` command to automatically generate TypeScript interfaces based on your Appwrite database schema. Learn more about [type generation](https://appwrite.io/docs/products/databases/type-generation).
### Error Handling
The Appwrite Web SDK raises an `AppwriteException` object with `message`, `code` and `response` properties. You can handle any errors by catching the exception and present the `message` to the user or handle it yourself based on the provided error information. Below is an example.
```javascript
try {
const user = await account.create(ID.unique(), "email@example.com", "password", "Walter O'Brien");
console.log('User created:', user);
} catch (error) {
console.error('Appwrite error:', error.message);
}
```
### Learn more
You can use the following resources to learn more and get help
- 🚀 [Getting Started Tutorial](https://appwrite.io/docs/getting-started-for-web)
- 📜 [Appwrite Docs](https://appwrite.io/docs)
docs/sdks/web/README.md
-15
View File
@@ -1,15 +0,0 @@
## Getting Started
Initialise the Appwrite SDK in your code, and setup your API credentials:
```js
// Init your Web SDK
var appwrite = new Appwrite();
appwrite
.setEndpoint('http://localhost/v1') // Set only when using self-hosted solution
.setProject('455x34dfkj') // Your Appwrite Project UID
;
```