Comprehensive WebSim API and Client-Side Documentation

This documentation provides a thorough overview of the WebSim API and client-side TypeScript implementation. It is based on the following resources:

• WebSim API Schema
• WebSim Client-Side TypeScript Files
• WebSim API Documentation
• WebSim Functions Compared: Edit, Delve, and Generate
• Websim Plugin Documentation
• WebSim Intermediate Guide
• WebSim AI Advanced Guide - Guide to our new generated backend /api/ feature, HTMX streaming, and the !continue function
• WebSim UI Guide - Guide to the WebSim user interface
• Context Referencing Guide - Learn how to paste a WebSim URL into the prompt bar to add the code of that page into your current creation
• Video Game Creation Guide - Cubey's guide with great step-by-step tips and an example for creating video games in WebSim
• Filegarden Integration Guide - k.json's guide to using Filegarden with WebSim to import character models, audio, or objects
• Custom Profile Pages Guide - Learn how users are making custom and personalized profile pages

Table of Contents

1. API Overview
2. Key Endpoints
3. Pagination
4. Client-Side Implementation
5. Key Concepts
6. WebSim Socket
7. Simulated APIs
8. Error Handling
9. Fetch Patching
10. Best Practices
11. Best Practices for API Usage

1. API Overview

The WebSim API provides a comprehensive set of endpoints for interacting with various aspects of the WebSim platform. It is designed to support the creation, management, and discovery of web-based content and projects.

1.1 Base URL

All API requests should be prefixed with the following base URL:

/api/v1/

1.2 Authentication

Most endpoints require authentication. While the specific authentication method is not detailed in the provided schema, it's likely to use one of the following:

• Bearer tokens
• Session cookies
• API keys

1.3 Response Format

API responses are returned in JSON format. Successful responses typically include the requested data, while error responses include an error object with a message and potentially additional details.

1.4 Rate Limiting

While not explicitly mentioned in the schema, it's common for APIs to implement rate limiting. Be prepared to handle 429 (Too Many Requests) responses and implement appropriate backoff strategies.

2. Key Endpoints

2.1 Feed Management

2.2 User Management

2.3 Project Management

2.4 Site Management

2.5 Like Functionality

3. Pagination

Many endpoints in the WebSim API support cursor-based pagination. Use the following query parameters for pagination:

• first: Number of items to return from the beginning of the list.
• last: Number of items to return from the end of the list.
• before: Cursor indicating the start of the desired page (moving backwards).
• after: Cursor indicating the end of the desired page (moving forwards).

Paginated responses include a meta object with the following properties:

{
  "has_next_page": boolean,
  "has_previous_page": boolean,
  "start_cursor": string,
  "end_cursor": string
}

4. Client-Side Implementation

The client-side TypeScript implementation provides a set of utilities and interfaces for interacting with the WebSim platform. This section details the key components and their functionality.

4.1 WebSim API

The window.websim object provides methods for interacting with the WebSim platform:

interface WebSimAPI {
  getUser(): Promise;
  getColorScheme(): Promise<"light" | "dark">;
  experimental: {
    v0: {
      siteId: string;
      save(htmlContent: string): Promise<{ id: string }>;
      getHTML(siteId?: string): Promise;
      generate(prompt: string, options?: GenerateOptions): Promise<{ id: string }>;
    }
  };
  internal_only_experimental: {
    getIsLiked(args: { siteId: string }): Promise;
    setIsLiked(args: { siteId: string; isLiked: boolean }): Promise;
    sendViewStartEvent(args: { siteId: string }): Promise;
    sendViewEndEvent(args: { viewUuid: string }): Promise;
  }
}

4.1.1 getUser()

Retrieves the current user's information.

4.1.2 getColorScheme()

Retrieves the current color scheme preference (light or dark).

4.1.3 experimental.v0

Provides experimental methods for site manipulation:

• save(htmlContent: string): Saves HTML content for a site.
• getHTML(siteId?: string): Retrieves HTML content for a site.
• generate(prompt: string, options?: GenerateOptions): Generates a new site based on a prompt.

4.1.4 internal_only_experimental

Provides internal experimental methods:

• getIsLiked(args: { siteId: string }): Checks if a site is liked by the current user.
• setIsLiked(args: { siteId: string; isLiked: boolean }): Sets the like status for a site.
• sendViewStartEvent(args: { siteId: string }): Logs the start of a site view.
• sendViewEndEvent(args: { viewUuid: string }): Logs the end of a site view.

5. Key Concepts

5.1 Sites

Sites represent individual web pages or applications created within the WebSim platform. They have the following key properties:

• id: A unique identifier for the site.
• parent_id: The ID of the parent site, if applicable.
• created_at: The creation timestamp.
• state: The current state of the site (e.g., "initial", "generating", "done", "failed").
• owner: The user who created the site.
• title: The title of the site.
• url: The URL of the site.
• prompt: The prompt used to generate the site, if applicable.

5.2 Projects

Projects are collections of related sites or revisions. They have the following key properties:

• id: A unique identifier for the project.
• created_by: The user who created the project.
• created_at: The creation timestamp.
• updated_at: The last update timestamp.
• title: The title of the project.
• visibility: The visibility setting of the project (e.g., "public", "private", "unlisted").
• current_version: The current version number of the project.
• stats: Statistics about the project, including views and likes.

5.3 Feeds

Feeds provide streams of content, which can be trending items, user-specific content, or search results. The feed data typically includes:

• Site information
• Project information
• Engagement metrics (views, likes, remixes)
• Cursor information for pagination

6. WebSim Socket

The WebsimSocket class provides real-time communication capabilities, enabling collaborative features and live updates. It extends the standard WebSocket interface with additional WebSim-specific functionality.

6.1 Key Features

• Real-time messaging between clients
• Shared state management through the store property
• Built-in user presence tracking
• Event-based architecture for easy integration

6.2 Usage Example

const room = new WebsimSocket();

room.onmessage = (event) => {
  const data = event.data;
  // Handle incoming messages
};

room.onPeersChanged = (peers) => {
  // Update UI with connected peers
};

room.onRecordChanged = (id) => {
  // Handle changes to shared store records
};

// Send a message
room.send({
  type: "chatMessage",
  message: "Hello, world!",
});

// Update shared store
room.store.update({
  id: "gameState",
  dependencies: { score: 100 },
  updateFunction: (currentState) => ({
    ...currentState,
    score: score
  })
});

6.3 WebSim Socket Events

WebsimSocket broadcasts 2 built-in events to all clients:

1. connected: Triggered when a client connects to the room.
   Signature: { type: "connected", clientId: string, avatarUrl: string, username: string }
2. disconnected: Triggered when a client disconnects from the room.
   Signature: { type: "disconnected", clientId: string, avatarUrl: string, username: string }

6.4 WebSim Socket Store

The WebsimSocket provides a shared store for managing state across all connected clients:

// Get a value from the store
const value = await room.store.get('key');

// Update a value in the store
room.store.update({
  id: 'key',
  dependencies: { newValue: 42 },
  updateFunction: (currentValue) => newValue
});

// Reset the entire store
room.store.reset();

// Get all values from the store
const allValues = await room.store.getAll();

7. Simulated APIs

WebSim provides simulated APIs that can be used within the WebSim environment. These APIs allow you to interact with the platform and create dynamic content.

7.1 SQL API

The SQL API allows you to create and interact with a simulated database within your WebSim project.

async function createMessageTable() {
  let query = `CREATE TABLE if not exists message (id INTEGER PRIMARY KEY, msg TEXT)`;
  let results = await fetch('/api/v1/sql/?' + new URLSearchParams({sql: query}));
  let data = await results.json();
  console.log(data);
}

async function insertMessage(msg) {
  let query = `INSERT INTO message (msg) VALUES ('${msg}')`;
  let results = await fetch('/api/v1/sql/?' + new URLSearchParams({sql: query}));
  let data = await results.json();
  console.log(data);
}

async function fetchMessages() {
  let query = `SELECT * FROM message ORDER BY id ASC`;
  let results = await fetch('/api/v1/sql/?' + new URLSearchParams({sql: query}));
  let data = await results.json();
  return data;
}

7.2 WebSim Global Object

The WebSim global object provides access to various platform features and user information. Here are some key functions:

// Get the current user
const user = await window.websim.getUser();

// Navigate to a different page
window.websim.navigate('/some-page');

// Show a toast notification
window.websim.toast('Hello, World!');

// Get the current project ID
const projectId = window.websim.getProjectId();

// Check if the current user is the owner of the current project
const isOwner = window.websim.isOwner();

// Get the current project's visibility
const visibility = window.websim.getVisibility();

// Get the current user's role (if applicable)
const role = window.websim.getRole();

// Check if the current user has a specific permission
const hasPermission = window.websim.hasPermission('edit_project');

// Get the current project's slug
const slug = window.websim.getSlug();

// Get the current project's version
const version = window.websim.getVersion();

8. Error Handling

The client-side implementation includes error catching for unhandled rejections and general errors. This helps in identifying and debugging issues in the application.

window.addEventListener('unhandledrejection', (event) => {
  const error = {
    type: 'unhandledRejection',
    message: event.reason?.message || 'Unknown promise rejection',
    stack: event.reason?.stack,
  };
  parentApi.reportError(error);
});

window.addEventListener('error', (event) => {
  const error = {
    type: 'error',
    message: event.message,
    stack: event.error?.stack,
  };
  parentApi.reportError(error);
});

These error handlers report errors to the parent application, allowing for centralized error tracking and analysis.

9. Fetch Patching

The implementation patches the global fetch function to handle WebSim-specific API calls and add custom headers. This patching allows for:

• Automatic addition of authentication headers
• Handling of WebSim-specific endpoints
• Custom error handling and reporting

window.fetch = async function (a, options = {}) {
  const url = new URL(
    (a as Request)?.url ? String((a as Request).url) : String(a),
    window.location.origin
  );

  // Custom logic for WebSim API calls
  if (isWebSimApiCall(url)) {
    // Add custom headers
    options.headers = {
      ...options.headers,
      'Websim-Update': `${websimUpdateVersion}`,
    };

    // Handle request body
    if (options.body) {
      // Process body based on content type
    }

    // Make the API call using parentApi
    const response = await parentApi.fetchApi({
      url: url.toString(),
      options,
      originalOptions,
    });

    return new Response(response.body, response);
  }

  // For non-WebSim API calls, use the original fetch
  return originalFetch(url, options);
};

10. Best Practices

10.1 Error Handling

• Always wrap API calls in try-catch blocks to handle potential errors gracefully.
• Use the built-in error reporting mechanism to log errors for analysis.

10.2 Performance

• Minimize the number of API calls by batching requests when possible.
• Use pagination parameters (first, last, before, after) to limit the amount of data returned in a single request.

10.3 Security

• Never expose API keys or sensitive information in client-side code.
• Validate and sanitize all user inputs before sending them to the API.

10.4 Real-time Communication

• Use the WebsimSocket for real-time features to ensure efficient and consistent communication.
• Implement appropriate error handling and reconnection logic for WebSocket connections.

10.5 API Usage

• Prefer the use of the window.websim object for WebSim-specific functionality over direct API calls when possible.
• Keep track of API versioning and update your code accordingly when new versions are released.

11. Best Practices for API Usage

1. Caching: Implement caching for frequently accessed data to reduce API calls and improve performance.
2. Rate Limiting: Be mindful of API rate limits and implement request throttling to avoid exceeding limits.
3. Error Handling: Implement robust error handling for both API requests and simulated APIs.
4. Pagination: Use pagination features efficiently to handle large datasets and improve load times.
5. Security: Always use HTTPS for API requests and never expose sensitive information in client-side code.
6. Performance: Optimize API usage by requesting only the data you need and using appropriate filters and queries.
7. Testing: Thoroughly test your integrations, including error scenarios and edge cases.
8. Documentation: Keep your API usage well-documented for easier maintenance and collaboration.
9. Versioning: Be aware of API versions and update your integrations accordingly when new versions are released.
10. Feedback: Provide feedback to the WebSim team about API functionality, bugs, or feature requests to help improve the platform.