Space Members

Introduction to Space Members

The "space-members" domain in the FastAPI API (v0.1.0) is designed to manage membership and invitations within a collaborative space. This functionality is crucial for applications that require user management within defined groups or spaces, enabling seamless collaboration and access control.

Key Concepts and Entities

Spaces

A "space" is a virtual environment where members can collaborate. Each space is identified by a unique space_id.

Invites

Invites are used to request users to join a space. They can be created, modified, accepted, or deleted.

Members

Members are users who have accepted an invitation to join a space. Each member is identified by a principal_id.

Common Workflows

Managing Invites

1. List Invites: Retrieve all pending invites for a specific space.

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

2. Create an Invite: Send an invitation to a user to join a space.

   curl -X POST "https://api.example.com/v1/spaces/{space_id}/invites" \
   -H "Content-Type: application/json" \
   -H "X-API-Key: your_api_key" \
   -d '{"email": "user@example.com"}'

3. Patch an Invite: Modify an existing invite, such as updating the invitee's email.

   curl -X PATCH "https://api.example.com/v1/spaces/{space_id}/invites/{invite_id}" \
   -H "Content-Type: application/json" \
   -H "X-API-Key: your_api_key" \
   -d '{"email": "newuser@example.com"}'

4. Delete an Invite: Remove an invite if it is no longer needed.

   curl -X DELETE "https://api.example.com/v1/spaces/{space_id}/invites/{invite_id}" -H "X-API-Key: your_api_key"

5. Accept an Invite: A user accepts an invite to join the space.

   curl -X POST "https://api.example.com/v1/spaces/{space_id}/invites/{invite_id}/accept" -H "X-API-Key: your_api_key"

Managing Members

1. List Members: Retrieve a list of all members in a space.

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

2. Add a Member: Directly add a user to a space without an invite.

   curl -X POST "https://api.example.com/v1/spaces/{space_id}/members" \
   -H "Content-Type: application/json" \
   -H "X-API-Key: your_api_key" \
   -d '{"principal_id": "user123"}'

3. Patch a Member: Update member information, such as roles or permissions.

   curl -X PATCH "https://api.example.com/v1/spaces/{space_id}/members/{principal_id}" \
   -H "Content-Type: application/json" \
   -H "X-API-Key: your_api_key" \
   -d '{"role": "admin"}'

4. Remove a Member: Remove a member from a space.

   curl -X DELETE "https://api.example.com/v1/spaces/{space_id}/members/{principal_id}" -H "X-API-Key: your_api_key"

Important Considerations

• Authentication: Most endpoints require an X-API-Key header for authentication. Ensure that your API key is kept secure.
• Error Handling: Handle errors gracefully by checking response codes and messages. Common errors include unauthorized access and invalid parameters.
• Pagination: When listing invites or members, consider implementing pagination if the dataset is large to improve performance and usability.

By understanding and utilizing these endpoints, developers can effectively manage user participation within spaces, enhancing collaborative capabilities in their applications.