API Endpoints

Table of Contents

1. Authentication
2. Rate Limiting
3. Blog Posts
4. Comments
5. File Management
6. Photo Management
7. Albums
8. Error Handling

Authentication

Nexus now supports user authentication using JSON Web Tokens (JWT).

Sign Up

• POST /signup
• Body:

  {
    "username": "newuser",
    "password": "securepassword"
  }

• Response: Returns a success message

Sign In

• POST /signin
• Body:

  {
    "username": "existinguser",
    "password": "correctpassword"
  }

• Response: Returns a JWT token to be used for authenticated requests

Using Authentication

For authenticated endpoints, include the JWT token in the Authorization header:

Authorization: Bearer your_jwt_token_here

Rate Limiting

Rate limiting is implemented to prevent abuse of the API. The default configuration allows:

• 10 requests per second
• Burst of up to 30 requests

These values can be adjusted using the RATE_LIMIT_PER_SECOND and RATE_LIMIT_BURST environment variables.

Blog Posts

Create a Blog Post

• POST /api/v1/blog
• Authentication: Required
• Body:

  {
    "title": "Your Blog Post Title",
    "content": "Your blog post content goes here",
    "coverID": 123  // Optional: ID of the cover photo
  }

• Response: Returns the created blog post object

Get All Blog Posts

• GET /api/v1/blog
• Query Parameters:
  • page (optional): Page number for pagination (default: 1)
  • pageSize (optional): Number of items per page (default: 10)
• Response: Returns an array of blog post objects

Get a Specific Blog Post

• GET /api/v1/blog/:id
• Response: Returns the specified blog post object

Update a Blog Post

• PUT /api/v1/blog/:id
• Authentication: Required
• Body:

  {
    "title": "Updated Title",
    "content": "Updated content",
    "coverID": 456  // Optional: New cover photo ID
  }

• Response: Returns the updated blog post object

Delete a Blog Post

• DELETE /api/v1/blog/:id
• Authentication: Required
• Response: Returns a success message

Comments

Add a Comment

• POST /api/v1/comments
• Authentication: Required
• Body:

  {
    "content": "Your comment here",
    "blogPostID": 123  // ID of the blog post
  }

• Response: Returns the created comment object

Get Comments

• GET /api/v1/comments
• Query Parameters:
  • blogPostID: ID of the blog post
• Response: Returns an array of comment objects

Update a Comment

• PUT /api/v1/comments/:id
• Authentication: Required
• Body:

  {
    "content": "Updated comment content"
  }

• Response: Returns the updated comment object

Delete a Comment

• DELETE /api/v1/comments/:id
• Authentication: Required
• Response: Returns a success message

File Management

Upload a File

• POST /api/v1/files
• Authentication: Required
• Form Data:
  • file: The file to upload
  • path (optional): The directory path to store the file (default: root directory)
  • isDirectory (optional): Set to "true" if creating a directory (default: "false")
• Response: Returns the file object

List Files

• GET /api/v1/files
• Query Parameters:
  • path (optional): The directory path to list files from (default: root directory)
• Response: Returns an array of file objects in the specified directory

Get File or Directory Contents

• GET /api/v1/files/dir/*path
• Response:
  • If path is a file: Returns the file object
  • If path is a directory: Returns an array of file objects in the directory

Update File Metadata

• PUT /api/v1/files/:id
• Authentication: Required
• Body:

  {
    "name": "Updated file name"
  }

• Response: Returns the updated file object

Delete a File

• DELETE /api/v1/files/:id
• Authentication: Required
• Response: Returns a success message

Create a Directory

• POST /api/v1/directories
• Authentication: Required
• Body:

  {
    "name": "New Directory Name",
    "path": "/parent/directory/path"
  }

• Response: Returns the created directory object

Photo Management

Create a Photo

• POST /api/v1/photos
• Authentication: Required
• Body:

  {
    "title": "Photo Title",
    "description": "Photo description",
    "fileID": 123,  // ID of the associated file
    "width": 1920,
    "height": 1080
  }

• Response: Returns the created photo object

Get All Photos

• GET /api/v1/photos
• Query Parameters:
  • page (optional): Page number for pagination (default: 1)
  • pageSize (optional): Number of items per page (default: 10)
• Response: Returns an array of photo objects

Get a Specific Photo

• GET /api/v1/photos/:id
• Response: Returns the specified photo object

Update a Photo

• PUT /api/v1/photos/:id
• Authentication: Required
• Body:

  {
    "title": "Updated Title",
    "description": "Updated description",
    "fileID": 456,  // Optional: New associated file ID
    "width": 3840,
    "height": 2160
  }

• Response: Returns the updated photo object

Delete a Photo

• DELETE /api/v1/photos/:id
• Authentication: Required
• Response: Returns a success message

Albums

Create an Album

• POST /api/v1/albums
• Authentication: Required
• Body:

  {
    "name": "My New Album"
  }

• Response: Returns the created album object

Get All Albums

• GET /api/v1/albums
• Query Parameters:
  • page (optional): Page number for pagination (default: 1)
  • pageSize (optional): Number of items per page (default: 10)
• Response: Returns an array of album objects

Get a Specific Album

• GET /api/v1/albums/:id
• Response: Returns the specified album object with associated photos

Update an Album

• PUT /api/v1/albums/:id
• Authentication: Required
• Body:

  {
    "name": "Updated Album Name"
  }

• Response: Returns the updated album object

Delete an Album

• DELETE /api/v1/albums/:id
• Authentication: Required
• Response: Returns a success message

Add a Photo to an Album

• POST /api/v1/albums/:id/photos
• Authentication: Required
• Body:

  {
    "photoID": 123
  }

• Response: Returns a success message

Remove a Photo from an Album

• DELETE /api/v1/albums/:id/photos/:photoID
• Authentication: Required
• Response: Returns a success message

Error Handling

All endpoints will return appropriate HTTP status codes:

• 200: Successful operation
• 201: Successful creation
• 400: Bad request (e.g., invalid input)
• 401: Unauthorized (authentication required)
• 403: Forbidden (insufficient permissions)
• 404: Resource not found
• 429: Too Many Requests (rate limit exceeded)
• 500: Internal server error

Error responses will include a JSON object with an "error" field describing the issue.