AimableDocs
DocsAPI Reference

Projects

Introduction to Projects

The "projects" domain in the FastAPI API platform is designed to manage and organize work within a specified space. Projects serve as containers for tasks, resources, and team collaboration, enabling efficient project management and execution. This domain is crucial for developers looking to integrate project management capabilities into their applications, providing endpoints to create, update, and manage projects and their members.

Key Concepts and Entities

Projects

A project is a fundamental entity within a space, representing a collection of tasks and resources. Projects are identified by a unique project_id and are associated with a specific space_id.

Members

Members are users associated with a project. They can have different roles and permissions, allowing for collaborative work within a project. Members are identified by a member_id.

Spaces

Spaces are overarching containers that can hold multiple projects. Each project is uniquely associated with a space through the space_id.

Common Workflows

Listing Projects

To retrieve a list of all projects within a specific space, use the GET /v1/spaces/{space_id}/projects endpoint. This is useful for displaying available projects to users.

curl -X GET "https://api.example.com/v1/spaces/{space_id}/projects" \
     -H "X-API-Key: your_api_key"

Creating a Project

To create a new project, use the POST /v1/spaces/{space_id}/projects endpoint. This requires a JSON payload with project details.

curl -X POST "https://api.example.com/v1/spaces/{space_id}/projects" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: unique_key" \
     -H "X-API-Key: your_api_key" \
     -d '{"name": "New Project", "description": "Project description"}'

Managing Project Members

To manage members within a project, use the following endpoints:

  • List Members: GET /v1/spaces/{space_id}/projects/{project_id}/members
  • Add Member: POST /v1/spaces/{space_id}/projects/{project_id}/members
  • Update Member: PATCH /v1/spaces/{space_id}/projects/{project_id}/members/{member_id}
  • Remove Member: DELETE /v1/spaces/{space_id}/projects/{project_id}/members/{member_id}

Example to add a member:

curl -X POST "https://api.example.com/v1/spaces/{space_id}/projects/{project_id}/members" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: unique_key" \
     -H "X-API-Key: your_api_key" \
     -d '{"user_id": "user123", "role": "contributor"}'

Important Considerations

Authentication

Most endpoints require an X-API-Key header for authentication. Ensure that your API key is kept secure and is included in all requests.

Idempotency

For operations that create resources, such as creating a project or adding a member, use the Idempotency-Key header to prevent duplicate actions if a request is retried.

Error Handling

Handle errors gracefully by checking response status codes. Common errors include 400 for bad requests and 401 for unauthorized access. Implement retry logic where appropriate, especially for network-related errors.

Pagination

For endpoints that return lists, consider implementing pagination to handle large datasets efficiently. This will typically involve query parameters such as page and limit.

By understanding these concepts and workflows, developers can effectively integrate project management features into their applications using the FastAPI API platform.