Table of Contents

Class ProjectsController

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

Provides API endpoints for project management including creation, retrieval, search, joining, and leaving projects.

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

Remarks

All endpoints require authentication (JWT token). Users can:

  • Create new projects (becomes project owner)
  • View their own projects and projects they are members of
  • Search and browse all projects
  • Join projects (creates membership request or direct membership)
  • Leave projects (removes membership)

Project owners have full control over their projects. Profile photo URLs for owners and members are automatically converted to presigned URLs (15-minute TTL) for secure access.

Constructors

ProjectsController(IProjectService)

Initializes a new instance of the ProjectsController class.

public ProjectsController(IProjectService projectService)

Parameters

projectService IProjectService

Service for project operations.

Methods

CreateProject(CreateProjectRequest, CancellationToken)

Creates a new project with the authenticated user as the owner.

[HttpPost]
public Task<ActionResult<ProjectDto>> CreateProject(CreateProjectRequest request, CancellationToken cancellationToken)

Parameters

request CreateProjectRequest

The project creation request containing project details, category, skills, and builder tags.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult<ProjectDto>>

201 Created: Returns created ProjectDto with Location header pointing to the new project

400 Bad Request: Invalid request data or invalid category/status

Remarks

Requires authentication. The authenticated user becomes the project owner. The project is created with the specified category, status (defaults to "Idea" if not provided), skills, and builder tags.

CreateProjectInvitation(Guid, CreateProjectInvitationRequest, CancellationToken)

Legacy endpoint for creating project invitations (deprecated - redirects to ProjectInvitationsController).

[HttpPost("{id}/invitations")]
public Task<IActionResult> CreateProjectInvitation(Guid id, CreateProjectInvitationRequest request, CancellationToken cancellationToken)

Parameters

id Guid

The unique identifier of the project.

request CreateProjectInvitationRequest

The invitation creation request (not used, endpoint is deprecated).

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<IActionResult>

400 Bad Request: Returns error message directing to use POST /api/invitations/projects/{projectId} instead

Remarks

This endpoint is kept for routing consistency but is deprecated. The actual implementation is in ProjectInvitationsController. Clients should use POST /api/invitations/projects/{projectId} instead.

GetMyProjects(CancellationToken)

Retrieves all projects associated with the authenticated user (owned and member projects).

[HttpGet]
public Task<ActionResult<List<ProjectDto>>> GetMyProjects(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult<List<ProjectDto>>>

200 OK: Returns list of ProjectDto objects

400 Bad Request: Error retrieving projects

Remarks

Requires authentication. Returns projects where the user is either the owner or a member. For each project, includes the user's role (Owner or Member) and pending invitation/join request counts.

GetProject(Guid, CancellationToken)

Retrieves detailed information for a specific project.

[HttpGet("{id}")]
public Task<ActionResult<ProjectDto>> GetProject(Guid id, CancellationToken cancellationToken)

Parameters

id Guid

The unique identifier of the project to retrieve.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult<ProjectDto>>

200 OK: Returns ProjectDto with complete project information

404 Not Found: Project not found

Remarks

Requires authentication. Returns project details including owner, members, skills, builder tags, and the authenticated user's role in the project. Profile photo URLs are converted to presigned URLs.

JoinProject(Guid, CancellationToken)

Joins a project, creating a membership relationship for the authenticated user.

[HttpPost("{id}/join")]
public Task<IActionResult> JoinProject(Guid id, CancellationToken cancellationToken)

Parameters

id Guid

The unique identifier of the project to join.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<IActionResult>

200 OK: Returns { "message": "Successfully joined project" }

400 Bad Request: Project not found, user already a member, or other error

Remarks

Requires authentication. Creates an active membership for the user in the project. If the user is already a member, returns an error. Project owners cannot join their own projects (they are already members).

LeaveProject(Guid, CancellationToken)

Removes the authenticated user's membership from a project.

[HttpPost("{id}/leave")]
public Task<IActionResult> LeaveProject(Guid id, CancellationToken cancellationToken)

Parameters

id Guid

The unique identifier of the project to leave.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<IActionResult>

200 OK: Returns { "message": "Successfully left project" }

403 Forbidden: User is the project owner (owners cannot leave their own projects)

400 Bad Request: Project not found or user is not a member

Remarks

Requires authentication. Project owners cannot leave their own projects - they must transfer ownership first. Regular members can leave at any time, which removes their active membership.

SearchProjects(SearchProjectsRequest, CancellationToken)

Searches and retrieves projects with pagination and optional filtering.

[HttpGet("search")]
public Task<ActionResult<object>> SearchProjects(SearchProjectsRequest request, CancellationToken cancellationToken)

Parameters

request SearchProjectsRequest

Search request containing search term, category, status, pagination parameters, and optional filters.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ActionResult<object>>

200 OK: Returns { "projects": [...], "totalCount": int, "page": int, "pageSize": int }

Remarks

Requires authentication. Supports searching by name/description, filtering by category and status, and pagination. Search is case-insensitive and matches project names and descriptions.

Edit this page