Table of Contents

Class ForumController

Namespace
Builvero.Api.Controllers
Assembly
Builvero.Api.dll

Provides API endpoints for forum operations including topics, messages, and subscriptions.

[ApiController]
[Route("api")]
[Authorize]
public class ForumController : ControllerBase
Inheritance
ForumController
Inherited Members

Remarks

All endpoints require authentication (JWT token). Access control:

  • Regular users must be active project members to view/create topics and messages
  • Admins, moderators, and team members have elevated access and can view deleted content
  • Users can subscribe/unsubscribe to topics for email notifications

Constructors

ForumController(IForumService)

Initializes a new instance of the ForumController class.

public ForumController(IForumService forumService)

Parameters

forumService IForumService

Service for forum operations.

Methods

AddMessage(Guid, AddMessageRequest, CancellationToken)

Adds a new message to an existing forum topic.

[HttpPost("forum/topics/{topicId}/messages")]
public Task<ActionResult<ProjectForumMessageDto>> AddMessage(Guid topicId, AddMessageRequest request, CancellationToken cancellationToken = default)

Parameters

topicId Guid

The unique identifier of the topic to add the message to.

request AddMessageRequest

The message request containing the message body.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult<ProjectForumMessageDto>>

201 Created: Returns created ProjectForumMessageDto with Location header pointing to the topic

403 Forbidden: User is not an admin/moderator/team member and is not an active project member

400 Bad Request: Topic not found, invalid request data, or other error

Remarks

Requires authentication. The message is added to the topic and email notifications are sent to subscribed users.

CreateTopic(Guid, CreateTopicRequest, CancellationToken)

Creates a new forum topic in a project with an initial message.

[HttpPost("projects/{projectId}/forum/topics")]
public Task<ActionResult<ProjectForumTopicDto>> CreateTopic(Guid projectId, CreateTopicRequest request, CancellationToken cancellationToken = default)

Parameters

projectId Guid

The unique identifier of the project where the topic should be created.

request CreateTopicRequest

The topic creation request containing title and body.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult<ProjectForumTopicDto>>

201 Created: Returns created ProjectForumTopicDto with Location header

403 Forbidden: User is not an admin/moderator/team member and is not an active project member

400 Bad Request: Invalid request data, topic title not unique, or other error

Remarks

Requires authentication. Topic titles must be unique within a project. Email notifications are sent to subscribed users.

GetSubscriptionState(Guid, Guid?, CancellationToken)

Retrieves the forum subscription state for a project or specific topic.

[HttpGet("projects/{projectId}/forum/subscription")]
public Task<ActionResult<ForumSubscriptionStateDto>> GetSubscriptionState(Guid projectId, Guid? topicId, CancellationToken cancellationToken = default)

Parameters

projectId Guid

The unique identifier of the project.

topicId Guid?

Optional topic ID. If provided, returns subscription state for that topic; otherwise returns global project subscription state.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult<ForumSubscriptionStateDto>>

200 OK: Returns ForumSubscriptionStateDto with subscription information

400 Bad Request: Error retrieving subscription state

Remarks

Requires authentication. Returns whether the user is subscribed to all project notifications (global subscription) and/or to a specific topic. Used by the UI to display current subscription status.

GetTopic(Guid, bool, CancellationToken)

Retrieves a specific forum topic with all its messages.

[HttpGet("forum/topics/{topicId}")]
public Task<ActionResult<ProjectForumTopicDto>> GetTopic(Guid topicId, bool includeDeleted = false, CancellationToken cancellationToken = default)

Parameters

topicId Guid

The unique identifier of the topic to retrieve.

includeDeleted bool

Whether to include soft-deleted messages (only effective for admins/moderators/team members).

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult<ProjectForumTopicDto>>

200 OK: Returns ProjectForumTopicDto with topic details and all messages

404 Not Found: Topic not found

403 Forbidden: User is not an admin/moderator/team member and is not an active project member

400 Bad Request: Error retrieving topic

Remarks

Requires authentication. Regular users never see deleted messages, even if includeDeleted is true. Returns the topic with all its messages ordered by creation date.

GetTopics(Guid, bool, CancellationToken)

Retrieves all forum topics for a project.

[HttpGet("projects/{projectId}/forum/topics")]
public Task<ActionResult<IReadOnlyList<ProjectForumTopicDto>>> GetTopics(Guid projectId, bool includeDeleted = false, CancellationToken cancellationToken = default)

Parameters

projectId Guid

The unique identifier of the project whose topics should be retrieved.

includeDeleted bool

Whether to include soft-deleted topics (only effective for admins/moderators/team members).

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult<IReadOnlyList<ProjectForumTopicDto>>>

200 OK: Returns list of ProjectForumTopicDto objects

403 Forbidden: User is not an admin/moderator/team member and is not an active project member

400 Bad Request: Error retrieving topics

Remarks

Requires authentication. Regular users never see deleted topics, even if includeDeleted is true.

SetGlobalSubscription(Guid, SetGlobalSubscriptionRequest, CancellationToken)

Sets the global forum subscription preference for a project (subscribes or unsubscribes from all project notifications).

[HttpPost("projects/{projectId}/forum/subscription/global")]
public Task<IActionResult> SetGlobalSubscription(Guid projectId, SetGlobalSubscriptionRequest request, CancellationToken cancellationToken = default)

Parameters

projectId Guid

The unique identifier of the project.

request SetGlobalSubscriptionRequest

The subscription request containing the ReceiveAll preference.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<IActionResult>

200 OK: Returns { "message": "Subscription updated" }

400 Bad Request: Error updating subscription

Remarks

Requires authentication. Sets whether the user receives email notifications for all forum activity in the project. If ReceiveAll is true, the user receives notifications for all new topics and messages. If false, the user only receives notifications for topics they are explicitly subscribed to.

SetTopicSubscription(Guid, SetTopicSubscriptionRequest, CancellationToken)

Sets the subscription preference for a specific forum topic (subscribes or unsubscribes from topic notifications).

[HttpPost("forum/topics/{topicId}/subscription")]
public Task<IActionResult> SetTopicSubscription(Guid topicId, SetTopicSubscriptionRequest request, CancellationToken cancellationToken = default)

Parameters

topicId Guid

The unique identifier of the topic.

request SetTopicSubscriptionRequest

The subscription request containing the IsSubscribed preference.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<IActionResult>

200 OK: Returns { "message": "Subscription updated" }

400 Bad Request: Error updating subscription

Remarks

Requires authentication. Sets whether the user receives email notifications for new messages in this specific topic. If IsSubscribed is true, the user receives notifications for all new messages in the topic. If false, the user does not receive notifications for this topic (unless they have global subscription enabled for the project).

Edit this page