Skip to main content

API Reference

Reference for service functions and Appwrite operations.

Appwrite Client Setup

import { Client, Databases, Storage, Account, ID, Query } from 'appwrite';

const client = new Client()
  .setEndpoint(import.meta.env.VITE_APPWRITE_ENDPOINT)
  .setProject(import.meta.env.VITE_APPWRITE_PROJECT_ID);

export const databases = new Databases(client);
export const storage = new Storage(client);
export const account = new Account(client);
export { ID, Query };

Database Operations

List Documents

import { databases, Query } from './appwrite';

// Basic list
const blogs = await databases.listDocuments(
  'portfolio_db',
  'blogs'
);

// With queries
const featuredBlogs = await databases.listDocuments(
  'portfolio_db',
  'blogs',
  [
    Query.equal('featured', true),
    Query.orderDesc('publishDate'),
    Query.limit(10)
  ]
);

Get Single Document

const blog = await databases.getDocument(
  'portfolio_db',
  'blogs',
  'document_id'
);

Create Document

import { ID } from 'appwrite';

const newBlog = await databases.createDocument(
  'portfolio_db',
  'blogs',
  ID.unique(), // Auto-generate ID
  {
    title: 'My Blog Post',
    category: 'Technology',
    description: 'A great post...',
    // ... other fields
  }
);

Update Document

const updated = await databases.updateDocument(
  'portfolio_db',
  'blogs',
  'document_id',
  {
    title: 'Updated Title',
    // Only include fields to update
  }
);

Delete Document

await databases.deleteDocument(
  'portfolio_db',
  'blogs',
  'document_id'
);

Query Methods

MethodDescriptionExample
Query.equal(attr, value)Exact matchQuery.equal('category', 'Tech')
Query.notEqual(attr, value)Not equalQuery.notEqual('status', 'draft')
Query.lessThan(attr, value)Less thanQuery.lessThan('price', 100)
Query.greaterThan(attr, value)Greater thanQuery.greaterThan('likes', 10)
Query.search(attr, value)Full-text searchQuery.search('title', 'react')
Query.orderAsc(attr)Sort ascendingQuery.orderAsc('createdAt')
Query.orderDesc(attr)Sort descendingQuery.orderDesc('publishDate')
Query.limit(n)Limit resultsQuery.limit(10)
Query.offset(n)Skip resultsQuery.offset(20)
Query.contains(attr, value)Array containsQuery.contains('tags', 'react')

Complex Queries

// Pagination
const page2 = await databases.listDocuments(
  'portfolio_db',
  'blogs',
  [
    Query.orderDesc('publishDate'),
    Query.limit(10),
    Query.offset(10) // Skip first 10
  ]
);

// Multiple conditions
const filtered = await databases.listDocuments(
  'portfolio_db',
  'products',
  [
    Query.equal('category', 'Electronics'),
    Query.equal('onSale', true),
    Query.lessThan('price', 500),
    Query.orderAsc('price')
  ]
);

Storage Operations

Upload File

import { storage, ID } from './appwrite';

const file = await storage.createFile(
  'blog_images',      // Bucket ID
  ID.unique(),        // File ID
  document.getElementById('fileInput').files[0]
);

// Get file URL
const fileUrl = storage.getFileView('blog_images', file.$id);

Get File URL

// View URL (for images)
const viewUrl = storage.getFileView('bucket_id', 'file_id');

// Download URL
const downloadUrl = storage.getFileDownload('bucket_id', 'file_id');

// Preview URL (with transformations)
const previewUrl = storage.getFilePreview(
  'bucket_id',
  'file_id',
  400,  // width
  300,  // height
  'center', // gravity
  90    // quality
);

Delete File

await storage.deleteFile('bucket_id', 'file_id');

Authentication

Login

import { account } from './appwrite';

const session = await account.createEmailPasswordSession(
  'user@example.com',
  'password'
);

Get Current User

try {
  const user = await account.get();
  console.log('Logged in as:', user.email);
} catch (error) {
  console.log('Not logged in');
}

Logout

await account.deleteSession('current');

Create Account

const user = await account.create(
  ID.unique(),
  'user@example.com',
  'password',
  'User Name' // Optional
);

Service Examples

Blog Service

// src/lib/blogService.js
export const blogService = {
  async listAll() {
    return await databases.listDocuments(
      DATABASE_ID,
      'blogs',
      [Query.orderDesc('publishDate')]
    );
  },

  async listFeatured() {
    return await databases.listDocuments(
      DATABASE_ID,
      'blogs',
      [
        Query.equal('featured', true),
        Query.orderDesc('publishDate'),
        Query.limit(6)
      ]
    );
  },

  async getBySlug(slug) {
    const result = await databases.listDocuments(
      DATABASE_ID,
      'blogs',
      [Query.equal('customSlug', slug)]
    );
    return result.documents[0] || null;
  },

  async listByCategory(category) {
    return await databases.listDocuments(
      DATABASE_ID,
      'blogs',
      [
        Query.equal('category', category),
        Query.orderDesc('publishDate')
      ]
    );
  }
};
// src/lib/shortlinkService.js
export const shortlinkService = {
  async getByPath(path) {
    const result = await databases.listDocuments(
      DATABASE_ID,
      'shortlinks',
      [
        Query.equal('customPath', path.toLowerCase()),
        Query.equal('isActive', true)
      ]
    );
    return result.documents[0] || null;
  },

  async incrementClicks(id, currentCount) {
    return await databases.updateDocument(
      DATABASE_ID,
      'shortlinks',
      id,
      { clickCount: currentCount + 1 }
    );
  },

  async recordAnalytics(shortlinkId, data) {
    return await databases.createDocument(
      DATABASE_ID,
      'shortlink_analytics',
      ID.unique(),
      {
        shortlinkId,
        timestamp: new Date().toISOString(),
        ...data
      }
    );
  }
};

Image Upload Helper

// src/lib/imageService.js
export const imageService = {
  async upload(bucketId, file) {
    const uploaded = await storage.createFile(
      bucketId,
      ID.unique(),
      file
    );
    
    const url = storage.getFileView(bucketId, uploaded.$id);
    
    return {
      id: uploaded.$id,
      url: url.href
    };
  },

  async delete(bucketId, fileId) {
    await storage.deleteFile(bucketId, fileId);
  },

  getPreviewUrl(bucketId, fileId, width = 400, height = 300) {
    return storage.getFilePreview(
      bucketId,
      fileId,
      width,
      height
    ).href;
  }
};

Error Handling

try {
  const result = await databases.listDocuments(...);
} catch (error) {
  if (error.code === 404) {
    console.log('Collection not found');
  } else if (error.code === 401) {
    console.log('Not authorized');
  } else if (error.code === 403) {
    console.log('Permission denied');
  } else {
    console.log('Error:', error.message);
  }
}

Common Error Codes

CodeMeaningSolution
401UnauthorizedCheck authentication
403ForbiddenCheck permissions
404Not FoundCheck collection/document ID
409ConflictDuplicate unique value
413Payload Too LargeReduce file/data size
429Rate LimitedSlow down requests