Skip to content

Latest commit

 

History

History
2259 lines (1783 loc) · 45.4 KB

api.md

File metadata and controls

2259 lines (1783 loc) · 45.4 KB

API Documentation

Comprehensive REST API Reference for Diora Platform

Authentication, endpoints, and data models for developers

API Status Docs

Overview

This document provides comprehensive information about the Diora REST API endpoints, authentication, and data models.

Base URL

Development: http://localhost:5010/api
Production: https://diora.onrender.com/api

Route Structure Overview

The API is organized into the following route groups:

Authentication Routes /auth
User Management /user
Post Management /post
Comment System /comment
Product Catalog /product
Shop System /shop
Shopping Cart /cart
Wishlist /wishlist
Order Management /order
Messaging System /message
Review System /review
Search Features /search & /userSearch
Notifications /notification
Reports & Moderation /report
Admin Panel /admin
Payment Integration /stripe
File Uploads /upload
System Webhooks /webhook

Authentication

The API uses JWT (JSON Web Tokens) for authentication. Include the token in the Authorization header for protected routes:

Authorization: Bearer <your_jwt_token>

User Types and Permissions

  • User: Regular users who can post outfits, shop, and interact socially
  • Shop: Business accounts that can list products and manage orders
  • Admin: Platform administrators with full system access

Error Handling

All API responses follow this format:

{
  "status": boolean,
  "message": "string",
  "data": object (optional)
}

HTTP Status Codes

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 500 - Internal Server Error

Authentication Endpoints

POST /auth/signup

Register a new user account.

Request Body:

{
  "email": "user@example.com",
  "username": "username",
  "fullName": "John Doe",
  "password": "password123"
}

Response:

{
  "status": true,
  "user": {
    "_id": "user_id",
    "email": "user@example.com",
    "username": "username",
    "fullName": "John Doe",
    "type": "user",
    "createdAt": "2025-01-01T00:00:00.000Z"
  },
  "token": "jwt_token"
}

POST /auth/login

Authenticate existing user.

Request Body:

{
  "username": "username_or_email",
  "password": "password123"
}

Response:

{
  "status": true,
  "user": {
    "_id": "user_id",
    "username": "username",
    "fullName": "John Doe",
    "type": "user",
    "status": "active"
  },
  "token": "jwt_token",
  "message": "Login successful"
}

User Management Endpoints

GET /user/me

Requires Authentication

Get current user profile information.

Response:

{
  "status": true,
  "user": {
    "_id": "user_id",
    "username": "username",
    "fullName": "John Doe",
    "avatar": "image_url",
    "bio": "User bio",
    "followers": ["user_id_1"],
    "following": ["user_id_2"],
    "type": "user"
  }
}

GET /user/:userId

Requires Authentication

Get specific user profile.

Response: Same as /user/me

GET /user/trending

Requires Authentication

Get trending users based on followers and activity.

Response:

{
  "status": true,
  "users": [
    {
      "_id": "user_id",
      "username": "trendinguser",
      "fullName": "Trending User",
      "avatar": "avatar_url",
      "followers": 500,
      "postsCount": 25,
      "type": "user"
    }
  ]
}

GET /user/settings/:userId

Requires Authentication

Get user's privacy and notification settings.

Response:

{
  "status": true,
  "settings": {
    "privacy": {
      "profileVisibility": "public",
      "allowMessages": true,
      "showOnlineStatus": true
    },
    "notifications": {
      "pushNotifications": true,
      "emailNotifications": false,
      "likeNotifications": true,
      "commentNotifications": true
    }
  }
}

PUT /user/settings

Requires Authentication

Update user settings.

Request Body:

{
  "privacy": {
    "profileVisibility": "private",
    "allowMessages": false
  },
  "notifications": {
    "pushNotifications": false
  }
}

PUT /user/update/security

Requires Authentication

Update user password.

Request Body:

{
  "currentPassword": "oldpassword",
  "newPassword": "newpassword123"
}

PUT /user/update/email

Requires Authentication

Update user email address.

Request Body:

{
  "newEmail": "newemail@example.com",
  "password": "currentpassword"
}

PUT /user/complete-onboarding

Requires Authentication

Mark user onboarding as complete.

Request Body:

{
  "interests": ["fashion", "streetwear"],
  "location": "New York"
}

PUT /user/complete-shop-onboarding

Requires Authentication (Shop owners only)

Complete shop onboarding process.

Request Body:

{
  "businessDetails": {
    "category": "fashion",
    "description": "Premium clothing store"
  }
}

PUT /user/update-shop-details

Requires Authentication (Shop owners only)

Update shop-specific details.

Request Body:

{
  "businessName": "New Shop Name",
  "businessDescription": "Updated description"
}

POST /user/upload-image

Requires Authentication

Upload user image (avatar or other).

Request Body (multipart/form-data):

  • image: file (required)

PUT /user/profile

Requires Authentication

Update user profile information.

Request Body (multipart/form-data):

  • fullName: string (optional)
  • bio: string (optional)
  • avatar: file (optional)

PUT /user/follow/:targetUserId

Requires Authentication

Follow or unfollow a user.

Response:

{
  "status": true,
  "message": "User followed successfully"
}

POST /user/request-promotion

Requires Authentication

Request promotion from user to shop owner.

Request Body (multipart/form-data):

  • businessName: string
  • businessDescription: string
  • businessType: string
  • yearsInBusiness: string
  • expectedProducts: string
  • additionalInfo: string
  • proofDocuments: files (required)

Post Management Endpoints

GET /post/

Requires Authentication

Get all posts in the platform feed.

Response:

{
  "status": true,
  "posts": [
    {
      "_id": "post_id",
      "caption": "My outfit today!",
      "imageUrl": "image_url",
      "user": {
        "_id": "user_id",
        "username": "username",
        "avatar": "avatar_url"
      },
      "stars": 15,
      "comments": 3,
      "createdAt": "2025-01-01T00:00:00.000Z"
    }
  ]
}

GET /post/trending

Requires Authentication

Get trending posts based on likes and engagement.

Response:

{
  "status": true,
  "posts": [
    {
      "_id": "post_id",
      "caption": "Trending outfit!",
      "imageUrl": "image_url",
      "user": {
        "_id": "user_id",
        "username": "username",
        "avatar": "avatar_url"
      },
      "stars": 250,
      "comments": 45,
      "createdAt": "2025-01-01T00:00:00.000Z"
    }
  ]
}

POST /post/create

Requires Authentication

Create a new outfit post.

Request Body (multipart/form-data):

  • caption: string
  • image: file (required)

GET /post/:postId

Requires Authentication

Get specific post details.

PUT /post/like/:postId

Requires Authentication

Like or unlike a post.

Response:

{
  "status": true,
  "message": "Post liked successfully",
  "stars": 16
}

GET /post/user/:userId

Requires Authentication

Get all posts by a specific user.

Product Management Endpoints

GET /product/

Requires Authentication

Get all available products.

Query Parameters:

  • category: string (optional)
  • sort: string (price_asc, price_desc, newest)
  • limit: number (default: 20)
  • page: number (default: 1)

Response:

{
  "status": true,
  "products": [
    {
      "_id": "product_id",
      "name": "Stylish Jacket",
      "description": "Perfect for winter",
      "price": 99.99,
      "imageUrl": "image_url",
      "category": "outerwear",
      "shopId": "shop_id",
      "inStock": true,
      "createdAt": "2025-01-01T00:00:00.000Z"
    }
  ]
}

GET /product/trending

Requires Authentication

Get trending products based on purchase volume and user engagement.

Response:

{
  "status": true,
  "products": [
    {
      "_id": "product_id",
      "name": "Trending Jacket",
      "description": "Most popular item this week",
      "price": 129.99,
      "imageUrl": "image_url",
      "category": "outerwear",
      "shopId": "shop_id",
      "purchaseCount": 50,
      "rating": 4.8
    }
  ]
}

GET /product/shop/:shopId

Requires Authentication

Get all products from a specific shop.

Query Parameters:

  • category: string (optional)
  • sort: string (price_asc, price_desc, newest)
  • limit: number (default: 20)

Response:

{
  "status": true,
  "products": [
    {
      "_id": "product_id",
      "name": "Shop Product",
      "price": 99.99,
      "imageUrl": "image_url",
      "inStock": true,
      "category": "clothing"
    }
  ],
  "shop": {
    "name": "Shop Name",
    "avatar": "shop_avatar_url"
  }
}

POST /product/

Requires Authentication (Shop owners only)

Create a new product listing.

Request Body (multipart/form-data):

  • name: string
  • description: string
  • price: number
  • category: string
  • sizes: array of strings (optional)
  • colors: array of strings (optional)
  • image: files (required)

GET /product/:productId

Requires Authentication

Get specific product details with reviews.

PUT /product/:productId

Requires Authentication (Shop owners only)

Update product information.

DELETE /product/:productId

Requires Authentication (Shop owners only)

Delete a product listing.

Shopping Cart Endpoints

GET /cart/

Requires Authentication

Get user's shopping cart.

Response:

{
  "status": true,
  "cart": {
    "_id": "cart_id",
    "userId": "user_id",
    "products": [
      {
        "productId": {
          "_id": "product_id",
          "name": "Product Name",
          "price": 99.99,
          "imageUrl": "image_url"
        },
        "quantity": 2,
        "size": "M",
        "variant": "Blue"
      }
    ]
  }
}

POST /cart/

Requires Authentication

Add item to cart.

Request Body:

{
  "productId": "product_id",
  "quantity": 1,
  "size": "M",
  "variant": "Blue"
}

PATCH /cart/

Requires Authentication

Update cart item quantity.

Request Body:

{
  "productId": "product_id",
  "quantity": 3
}

DELETE /cart/

Requires Authentication

Remove item from cart.

Request Body:

{
  "productId": "product_id"
}

Order Management Endpoints

POST /order/

Requires Authentication

Create a new order.

Request Body:

{
  "items": [
    {
      "productId": "product_id",
      "quantity": 2,
      "price": 99.99
    }
  ],
  "shippingAddress": {
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "country": "USA"
  }
}

GET /order/

Requires Authentication

Get user's order history.

GET /order/:orderId

Requires Authentication

Get specific order details.

PATCH /order/:orderId/status

Requires Authentication (Shop owners only)

Update order status.

Request Body:

{
  "status": "shipped",
  "trackingNumber": "1234567890"
}

Messaging Endpoints

GET /message/conversations

Requires Authentication

Get user's conversations list.

POST /message/conversations

Requires Authentication

Create or get conversation with another user.

Request Body:

{
  "otherUserId": "user_id"
}

GET /message/conversations/user/:otherUserId

Requires Authentication

Get or create conversation ID with a specific user.

Response:

{
  "status": true,
  "conversationId": "conversation_id"
}

POST /message/conversations/group

Requires Authentication

Create a new group conversation.

Request Body:

{
  "participants": ["user_id_1", "user_id_2", "user_id_3"],
  "name": "Group Name",
  "avatar": "optional_avatar_url"
}

Response:

{
  "status": true,
  "conversation": {
    "_id": "conversation_id",
    "type": "group",
    "name": "Group Name",
    "participants": ["user_id_1", "user_id_2"],
    "createdAt": "2026-01-10T00:00:00.000Z"
  }
}

PUT /message/conversations/:conversationId/leave

Requires Authentication

Leave a group conversation.

Response:

{
  "status": true,
  "message": "Left group successfully"
}

PUT /message/conversations/:conversationId/edit

Requires Authentication

Edit group conversation details.

Request Body:

{
  "name": "New Group Name",
  "avatar": "new_avatar_url"
}

Response:

{
  "status": true,
  "message": "Group updated successfully"
}

PUT /message/conversations/:conversationId/add-user

Requires Authentication

Add a user to a group conversation.

Request Body:

{
  "userId": "user_id_to_add"
}

Response:

{
  "status": true,
  "message": "User added to group successfully"
}

GET /message/conversations/:conversationId/messages

Requires Authentication

Get messages from a conversation.

POST /message/messages

Requires Authentication

Send a new message.

Request Body:

{
  "conversationId": "conversation_id",
  "content": "Hello there!",
  "type": "text"
}

PUT /message/conversations/:conversationId/read

Requires Authentication

Mark all messages in a conversation as read.

Response:

{
  "status": true,
  "message": "Conversation marked as read"
}

PUT /message/messages/:messageId/reaction

Requires Authentication

Add or remove a reaction to a message.

Request Body:

{
  "emoji": "❤️"
}

Response:

{
  "status": true,
  "message": "Reaction updated",
  "reactions": {
    "❤️": ["user_id_1", "user_id_2"]
  }
}

DELETE /message/messages/:messageId

Requires Authentication

Delete a message (soft delete - marked as deleted).

Response:

{
  "status": true,
  "message": "Message deleted successfully"
}

Review System Endpoints

POST /review/

Requires Authentication

Create a review for a product or shop.

Request Body (multipart/form-data):

  • targetId: string (product or shop ID)
  • targetType: string ("product" or "shop")
  • rating: number (1-5)
  • comment: string (optional)
  • images: files (optional)

GET /review/product/:productId

Requires Authentication

Get all reviews for a product.

GET /review/shop/:shopId

Requires Authentication

Get all reviews for a shop.

Search Endpoints

GET /search/

Requires Authentication

General search across posts, products, and users.

Query Parameters:

  • q: string (search query)
  • type: string (posts, products, users, shops)

GET /search/users

Requires Authentication

Search for users.

GET /search/shops

Requires Authentication

Search for shops.

GET /post/user/:userId/liked

Requires Authentication

Get posts liked by a specific user.

Response:

{
  "status": true,
  "posts": [
    {
      "_id": "post_id",
      "caption": "Liked post",
      "imageUrl": "image_url",
      "user": {
        "_id": "original_user_id",
        "username": "original_user",
        "avatar": "avatar_url"
      },
      "stars": 100,
      "likedAt": "2025-01-01T00:00:00.000Z"
    }
  ]
}

Comment Endpoints

POST /comment/create

Requires Authentication

Create a comment on a post.

Request Body:

{
  "postId": "post_id",
  "content": "Great outfit!"
}

POST /comment/reply/:commentId

Requires Authentication

Reply to a specific comment.

Request Body:

{
  "content": "Thank you!"
}

GET /comment/post/:postId

Requires Authentication

Get all comments for a specific post.

Response:

{
  "status": true,
  "comments": [
    {
      "_id": "comment_id",
      "content": "Great outfit!",
      "user": {
        "_id": "user_id",
        "username": "username",
        "avatar": "avatar_url"
      },
      "replies": [
        {
          "_id": "reply_id",
          "content": "Thank you!",
          "user": {
            "_id": "user_id",
            "username": "username"
          },
          "createdAt": "2025-01-01T00:00:00.000Z"
        }
      ],
      "createdAt": "2025-01-01T00:00:00.000Z"
    }
  ]
}

Shop Management Endpoints

GET /shop/

Requires Authentication

Get all shops on the platform.

Response:

{
  "status": true,
  "shops": [
    {
      "_id": "shop_id",
      "name": "Fashion Boutique",
      "description": "Premium fashion items",
      "avatar": "avatar_url",
      "coverImage": "cover_url",
      "followers": 150,
      "productsCount": 25,
      "rating": 4.5,
      "createdAt": "2025-01-01T00:00:00.000Z"
    }
  ]
}

GET /shop/trending

Requires Authentication

Get trending shops based on popularity metrics.

GET /shop/analytics

Requires Authentication (Shop owners only)

Get shop analytics and performance data.

Response:

{
  "status": true,
  "analytics": {
    "totalSales": 5000,
    "ordersCount": 50,
    "productsViews": 1500,
    "followersGrowth": 15,
    "topProducts": [
      {
        "productId": "product_id",
        "name": "Best Seller",
        "sales": 25
      }
    ]
  }
}

GET /shop/:shopId

Requires Authentication

Get specific shop profile and products.

POST /shop/

Requires Authentication

Create a new shop (promotion required).

PUT /shop/follow/:shopId

Requires Authentication

Follow or unfollow a shop.

PUT /shop/profile

Requires Authentication (Shop owners only)

Update shop profile with avatar and cover image.

Request Body (multipart/form-data):

  • name: string (optional)
  • description: string (optional)
  • avatar: file (optional)
  • coverImage: file (optional)

PUT /shop/:shopId

Requires Authentication (Shop owners only)

Update shop information.

DELETE /shop/:shopId

Requires Authentication (Shop owners only)

Delete shop account.

DELETE /cart/clear

Requires Authentication

Clear all items from the shopping cart.

Response:

{
  "status": true,
  "message": "Cart cleared successfully"
}

Wishlist Endpoints

GET /wishlist/

Requires Authentication

Get user's wishlist items.

Response:

{
  "status": true,
  "wishlist": {
    "_id": "wishlist_id",
    "userId": "user_id",
    "products": [
      {
        "_id": "product_id",
        "name": "Wishlist Item",
        "price": 79.99,
        "imageUrl": "image_url",
        "shopId": {
          "name": "Shop Name",
          "avatar": "shop_avatar"
        }
      }
    ]
  }
}

POST /wishlist/

Requires Authentication

Add product to wishlist.

Request Body:

{
  "productId": "product_id"
}

DELETE /wishlist/

Requires Authentication

Remove product from wishlist.

Request Body:

{
  "productId": "product_id"
}

POST /wishlist/toggle

Requires Authentication

Toggle product in/out of wishlist.

Request Body:

{
  "productId": "product_id"
}

Advanced User Search Endpoints

GET /userSearch/users

Requires Authentication

Advanced user search with filters.

Query Parameters:

  • query: string (search term)
  • type: string (user type filter)
  • location: string (location filter)

GET /userSearch/shops

Requires Authentication

Advanced shop search with filters.

Query Parameters:

  • query: string (search term)
  • category: string (shop category)
  • rating: number (minimum rating)

GET /userSearch/all

Requires Authentication

Combined search for both users and shops.

File Upload Endpoints

POST /upload/group-photo/:conversationId

Requires Authentication

Upload group photo for a conversation.

Request Body (multipart/form-data):

  • photo: file (required)

Response:

{
  "status": true,
  "message": "Group photo uploaded successfully",
  "photoUrl": "uploaded_photo_url"
}

Webhook Endpoints

POST /webhook/

Internal Use - Stripe Webhooks

Handle Stripe payment webhooks for order completion.

Note: This endpoint is used internally by Stripe and requires proper webhook signature verification.

Notification Endpoints

GET /notification/

Requires Authentication

Get user's notifications.

Query Parameters:

  • limit: number (default: 20)
  • page: number (default: 1)
  • unreadOnly: boolean (optional)

Response:

{
  "status": true,
  "notifications": [
    {
      "_id": "notification_id",
      "type": "like",
      "title": "New Like",
      "message": "John liked your post",
      "isRead": false,
      "data": {
        "postId": "post_id",
        "userId": "user_id"
      },
      "createdAt": "2026-01-10T00:00:00.000Z"
    }
  ],
  "unreadCount": 5
}

POST /notification/add

Internal Use Only

Create a new notification (used by backend systems).

Request Body:

{
  "userId": "user_id",
  "type": "follow",
  "title": "New Follower",
  "message": "Jane started following you",
  "data": {
    "followerId": "follower_id"
  }
}

PATCH /notification/mark-as-read/:notificationId

Requires Authentication

Mark specific notification as read.

Response:

{
  "status": true,
  "message": "Notification marked as read"
}

PATCH /notification/mark-all-as-read

Requires Authentication

Mark all notifications as read.

Response:

{
  "status": true,
  "message": "All notifications marked as read"
}

Administrative Endpoints

All admin endpoints require admin authentication

GET /admin/stats

Requires Admin Authentication

Get platform statistics.

Response:

{
  "status": true,
  "stats": {
    "users": {
      "total": 1000,
      "shops": 50,
      "admins": 3,
      "newThisMonth": 25
    },
    "content": {
      "posts": 5000,
      "products": 500,
      "comments": 2000
    },
    "orders": {
      "total": 200,
      "thisMonth": 15
    }
  }
}

GET /admin/health

Requires Admin Authentication

System health check and diagnostics.

Response:

{
  "status": true,
  "health": {
    "database": "connected",
    "redis": "connected",
    "uptime": "72h 15m",
    "memory": {
      "used": "512MB",
      "total": "2GB"
    },
    "lastBackup": "2026-01-09T00:00:00.000Z"
  }
}

GET /admin/users/search

Requires Admin Authentication

Search and manage users.

Query Parameters:

  • query: string (search term)
  • type: string (user, shop, admin)
  • status: string (active, suspended, banned)

POST /admin/users/:userId/suspend

Requires Admin Authentication

Suspend a user account.

Request Body:

{
  "duration": 7,
  "reason": "Violation of community guidelines"
}

Response:

{
  "status": true,
  "message": "User suspended successfully",
  "suspendedUntil": "2026-01-17T00:00:00.000Z"
}

POST /admin/users/:userId/ban

Requires Admin Authentication

Ban a user account permanently.

Request Body:

{
  "reason": "Repeated violations",
  "permanent": true
}

Response:

{
  "status": true,
  "message": "User banned successfully"
}

POST /admin/users/:userId/unban

Requires Admin Authentication

Unban a previously banned user.

Response:

{
  "status": true,
  "message": "User unbanned successfully"
}

POST /admin/users/:userId/warn

Requires Admin Authentication

Send a warning to a user.

Request Body:

{
  "message": "Please follow community guidelines",
  "severity": "medium"
}

Response:

{
  "status": true,
  "message": "Warning sent successfully"
}

GET /admin/posts/search

Requires Admin Authentication

Search and filter posts for moderation.

Query Parameters:

  • query: string (search term)
  • reported: boolean (show only reported posts)
  • hidden: boolean (show hidden posts)
  • userId: string (filter by user)
  • limit: number (default: 20)

Response:

{
  "status": true,
  "posts": [
    {
      "_id": "post_id",
      "user": {
        "username": "user123",
        "fullName": "John Doe"
      },
      "caption": "Post caption",
      "reports": 3,
      "isHidden": false,
      "createdAt": "2026-01-10T00:00:00.000Z"
    }
  ]
}

POST /admin/posts/:postId/hide

Requires Admin Authentication

Hide a post from public view.

Request Body:

{
  "reason": "Inappropriate content"
}

Response:

{
  "status": true,
  "message": "Post hidden successfully"
}

POST /admin/posts/:postId/show

Requires Admin Authentication

Unhide a previously hidden post.

Response:

{
  "status": true,
  "message": "Post shown successfully"
}

GET /admin/products/search

Requires Admin Authentication

Search and filter products for moderation.

Query Parameters:

  • query: string (search term)
  • reported: boolean (show only reported products)
  • hidden: boolean (show hidden products)
  • shopId: string (filter by shop)
  • limit: number (default: 20)

Response:

{
  "status": true,
  "products": [
    {
      "_id": "product_id",
      "name": "Product Name",
      "shop": {
        "name": "Shop Name"
      },
      "price": 99.99,
      "reports": 1,
      "isHidden": false
    }
  ]
}

POST /admin/products/:productId/hide

Requires Admin Authentication

Hide a product from the marketplace.

Request Body:

{
  "reason": "Counterfeit or misleading"
}

Response:

{
  "status": true,
  "message": "Product hidden successfully"
}

POST /admin/products/:productId/show

Requires Admin Authentication

Unhide a previously hidden product.

Response:

{
  "status": true,
  "message": "Product shown successfully"
}

GET /admin/promotion-requests

Requires Admin Authentication

Get pending shop promotion requests.

PUT /admin/promotion-requests/:requestId

Requires Admin Authentication

Approve or reject promotion request.

Request Body:

{
  "action": "approve",
  "comments": "Application approved"
}

Content Moderation Endpoints

POST /report/

Requires Authentication

Report inappropriate content.

Request Body:

{
  "itemType": "post",
  "itemId": "post_id",
  "reason": "spam",
  "description": "This post contains spam content"
}

GET /report/

Requires Admin Authentication

Get all reports for moderation.

Query Parameters:

  • status: string (pending, under_review, resolved, dismissed)
  • type: string (post, product, shop, user, message)
  • limit: number (default: 20)

Response:

{
  "status": true,
  "reports": [
    {
      "_id": "report_id",
      "targetType": "post",
      "targetId": "post_id",
      "reporter": {
        "username": "reporter123"
      },
      "reason": "spam",
      "description": "Contains spam content",
      "status": "pending",
      "createdAt": "2026-01-10T00:00:00.000Z"
    }
  ]
}

GET /report/stats

Requires Admin Authentication

Get report statistics and trends.

Response:

{
  "status": true,
  "stats": {
    "total": 150,
    "pending": 25,
    "underReview": 10,
    "resolved": 100,
    "dismissed": 15,
    "byType": {
      "post": 80,
      "product": 40,
      "user": 20,
      "shop": 10
    }
  }
}

GET /report/:id

Requires Admin Authentication

Get detailed information about a specific report.

Response:

{
  "status": true,
  "report": {
    "_id": "report_id",
    "targetType": "post",
    "targetId": "post_id",
    "target": {
      "caption": "Post content",
      "imageUrl": "image_url"
    },
    "reporter": {
      "username": "reporter123",
      "email": "reporter@example.com"
    },
    "reason": "spam",
    "description": "Detailed description",
    "status": "pending",
    "createdAt": "2026-01-10T00:00:00.000Z"
  }
}

PUT /report/:id

Requires Admin Authentication

Update report status and add admin notes.

Request Body:

{
  "status": "under_review",
  "adminNotes": "Investigating the issue"
}

Response:

{
  "status": true,
  "message": "Report updated successfully"
}

POST /report/:id/moderate

Requires Admin Authentication

Take moderation action on a report.

Request Body:

{
  "action": "remove_content",
  "reason": "Violates community guidelines"
}

Response:

{
  "status": true,
  "message": "Moderation action completed"
}

DELETE /report/cleanup

Requires Admin Authentication

Clean up old resolved/dismissed reports (90+ days).

Response:

{
  "status": true,
  "message": "Cleanup completed",
  "deletedCount": 45
}

Stripe Integration Endpoints

POST /stripe/create-account-link

Requires Authentication (Shop owners only)

Create Stripe account link for shop setup.

POST /order/create-stripe-session

Requires Authentication

Create Stripe checkout session for order payment.

GET /stripe/check-onboarding-status

Requires Authentication (Shop owners only)

Check the onboarding status of shop's Stripe account.

Response:

{
  "status": true,
  "onboardingComplete": true,
  "accountId": "acct_stripe_account_id",
  "chargesEnabled": true,
  "payoutsEnabled": true
}

Real-time Features

The API supports real-time communication through WebSocket connections for:

  • Instant Messaging: Real-time message delivery
  • Live Notifications: Immediate notification updates
  • Online Status: User online/offline status
  • Typing Indicators: Message typing status

WebSocket Events

Connect to: wss://diora.onrender.com

Client Events:

  • register: Register user for real-time updates
  • join_conversation: Join specific conversation
  • typing_start: Indicate typing start
  • typing_stop: Indicate typing stop

Server Events:

  • message: New message received
  • notification: New notification
  • user_online: User came online
  • user_offline: User went offline
  • typing: Someone is typing

Rate Limiting

The API implements rate limiting:

  • General requests: 1000 requests per 15 minutes per IP
  • Authentication: Special handling for login/signup
  • File uploads: Additional restrictions apply

File Upload Guidelines

  • Images: JPG, PNG, GIF formats
  • Documents: PDF format for promotion requests
  • Size limits: 10MB per file
  • Multiple files: Up to 5 files per request (where supported)

Additional Endpoint Details

GET /order/success

Requires Authentication

Stripe payment success callback page.

Query Parameters:

  • session_id: string (Stripe session ID)

Response:

{
  "status": true,
  "message": "Payment successful",
  "order": {
    "_id": "order_id",
    "paymentStatus": "paid",
    "orderStatus": "confirmed"
  }
}

GET /order/cancel

Requires Authentication

Stripe payment cancellation callback page.

Response:

{
  "status": true,
  "message": "Payment cancelled",
  "redirectUrl": "/cart"
}

GET /order/shop

Requires Authentication (Shop owners only)

Get orders for the authenticated shop owner.

Query Parameters:

  • status: string (pending, confirmed, shipped, delivered)
  • limit: number (default: 20)
  • page: number (default: 1)

Response:

{
  "status": true,
  "orders": [
    {
      "_id": "order_id",
      "customer": {
        "fullName": "John Doe",
        "email": "john@example.com"
      },
      "items": [
        {
          "productId": "product_id",
          "quantity": 2,
          "price": 99.99
        }
      ],
      "total": 199.98,
      "status": "pending",
      "createdAt": "2025-01-01T00:00:00.000Z"
    }
  ]
}

PATCH /order/:orderId/cancel

Requires Authentication

Cancel a pending order.

Request Body:

{
  "reason": "Changed mind"
}

Response:

{
  "status": true,
  "message": "Order cancelled successfully",
  "refundStatus": "pending"
}

DELETE /notification/delete/:notificationId

Requires Authentication

Delete a specific notification.

Response:

{
  "status": true,
  "message": "Notification deleted successfully"
}

GET /review/reviewed/:userId/:targetType/:targetId

Requires Authentication

Check if user has already reviewed a product or shop.

Response:

{
  "status": true,
  "hasReviewed": true,
  "reviewId": "review_id"
}

PUT /review/:targetType/:id

Requires Authentication

Update an existing review.

Request Body (multipart/form-data):

  • rating: number (1-5)
  • comment: string (optional)
  • images: files (optional)

DELETE /review/:targetType/:id

Requires Authentication

Delete a review (only by review author).

Response:

{
  "status": true,
  "message": "Review deleted successfully"
}

Rate Limiting

The API implements rate limiting to ensure fair usage and system stability.

Rate Limit Details

Endpoint Type Requests Time Window Notes
Authentication 5 requests 15 minutes Login/Signup attempts
General API 100 requests 15 minutes Most GET/POST endpoints
File Upload 10 requests 15 minutes Image/file uploads
Admin Actions 50 requests 15 minutes Admin-only endpoints
Messaging 30 messages 1 minute Real-time messages

Rate Limit Headers

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704902400

Rate Limit Exceeded Response

When rate limit is exceeded, the API returns:

{
  "status": false,
  "message": "Rate limit exceeded. Please try again later.",
  "retryAfter": 300
}

HTTP Status Code: 429 Too Many Requests

Best Practices

  • Cache responses when possible to reduce API calls
  • Implement exponential backoff when retrying failed requests
  • Use WebSocket connections for real-time features instead of polling
  • Batch requests where the API supports it
  • Monitor rate limit headers to avoid hitting limits

Webhook Security

Stripe Webhook Verification

All Stripe webhooks must be verified using the webhook signature:

const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const sig = req.headers['stripe-signature'];
  
  try {
    const event = stripe.webhooks.constructEvent(
      req.body,
      sig,
      process.env.STRIPE_WEBHOOK_SECRET
    );
    // Process event
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }
});

Security Best Practices

  1. Always verify webhook signatures before processing
  2. Use HTTPS endpoints for webhooks in production
  3. Implement idempotency to handle duplicate webhook deliveries
  4. Log all webhook events for debugging and auditing
  5. Set up proper error handling and retry logic
  6. Validate webhook payload structure before processing

Error Codes Reference

Code Description Common Causes
AUTH_001 Invalid token Expired or malformed JWT
AUTH_002 Access denied Insufficient permissions
USER_001 User not found Invalid user ID
USER_002 Account suspended User account suspended
PROD_001 Product not found Invalid product ID
ORD_001 Order not found Invalid order ID
CART_001 Cart empty No items in cart