v1.0 -> v1.1

Migration Guide from API v1.0 to v1.1

This document provides a comprehensive guide for migrating applications from API v1.0 to v1.1. It covers new features, breaking changes, and database schema modifications.

For Application Developers (API Consumers)

This section details the changes that will affect client applications interacting with the API.

New Features

1. Real-time Notifications via WebSockets

API v1.1 introduces a WebSocket endpoint for real-time event notifications. This allows applications to receive live updates without constant polling.

• Endpoint: GET /ws?token={jwt_token}

• Connection: To connect, provide a valid JWT token as a query parameter.

• Notifications: The server will push JSON-formatted messages for the following events:

  • New Follower: When a user gains a new follower.

    • type: new_follower

    • payload: { "follower_id": <user_id> }

  • New Comment: When a post you authored receives a new comment.

    • type: new_comment

    • payload: { "post_id": <post_id>, "comment_id": <comment_id>, "commenter_id": <user_id> }

  • New Post Like: When a post you authored is liked.

    • type: post_like

    • payload: { "post_id": <post_id>, "liker_id": <user_id> }

2. Media Storage

A new endpoint is available for uploading media files.

• Endpoint: POST /media/upload

• Authentication: Requires a valid Bearer token.

• Request: multipart/form-data with a file field.

• Response: A JSON object containing the URL of the uploaded file.

  {
    "url": "https://your-cdn-domain/path/to/file.jpg",
    "filename": "original_filename.jpg",
    "stored_as": "uploads/timestamp_uuid.jpg"
  }

Breaking Changes

There are no breaking changes in this version. All v1.0 endpoints remain compatible.

Non-Breaking Changes (Additions)

Community Endpoints

• Edit Community Rules: You can now add or update the rules for a community you own.

  • Endpoint: PUT /communities/{id}/rules

  • Request Body:

    {
      "rules": ["Rule 1", "Rule 2"]
    }

Post Endpoints

• Edit a Post: Users can now edit their own posts.

  • Endpoint: PUT /posts/{id}/edit

  • Request Body:

    {
      "title": "New Title",
      "content": "New content for the post.",
      "nsfw": false
    }

• Delete a Post: Users can now delete their own posts.

  • Endpoint: DELETE /posts/{id}

Data Model Additions

• Community Model:

  • A new rules field has been added, which is an array of strings.

• Post Model:

  • edited: A new boolean field that is true if the post has been edited.

  • edited_at: A new integer (Unix timestamp) field indicating when the post was last edited.

For Maintainers (Database Migration)

To upgrade your database from v1.0 to v1.1, you need to apply the following SQL ALTER statements. These changes add new columns to the communities and posts tables to support the new features.

It is strongly recommended to back up your database before running these commands.

-- Add the 'rules' column to the 'communities' table
ALTER TABLE communities ADD COLUMN rules TEXT[] DEFAULT '{}';

-- Add the 'likes' column to the 'posts' table
ALTER TABLE posts ADD COLUMN likes INTEGER DEFAULT 0;

-- Add the 'edited' and 'edited_at' columns to the 'posts' table
ALTER TABLE posts ADD COLUMN edited BOOLEAN DEFAULT FALSE;
ALTER TABLE posts ADD COLUMN edited_at BIGINT;

After running these commands, your database schema will be aligned with API v1.1.