## Team API Documentation This API allows users to interact with teams by joining, leaving, or inviting others to collaborate. The endpoints also offer the ability to retrieve advertisements linked to teams, and to handle user invitations securely using authentication tokens. ### List of Contents - [Manage Teams](#manage-teams) - [Get Team(s)](#1-teams-list-index) - [Get Team](#2-show-team-single) - [Get Team Advertises](#3-list-team-advertisements) - [Team MemberShip](#team-membership) [Not Finished] - [Invite a User to Team](#1-invite-user-to-team) - [Join a Team](#2-join-team) - [Leave a Team](#3-leave-team) ### Authentication - Authentication is handled using [Sanctum](https://laravel.com/docs/sanctum) tokens. Ensure that you include a valid token in the `Authorization` header of your requests to access protected endpoints. ### Content Type - All API endpoints operate with `application/json` for both requests and responses. --- ## Manage Teams Team API provides endpoints to manage teams. including listing available teams, viewing specific team details and getting a specific advertisement for a team. ### 1. Teams List (Index) - **Endpoint**: `POST /api/v1/team/list` - **Description**: Retrieves a paginated list of all available teams based on optional filters and sorting options. - **Authentication**: No - **Permissions**: User #### Request Example: No parameters required. #### Request Parameters: | Parameter | Required/Optional | Type | Description | |-------------|-------------------|---------|--------------------------------------------------------------| | `per_page` | Optional | Integer | Number of teams to display per page. Default is 10. | | `page` | Optional | Integer | Page number to retrieve. Default is 1. | | `filters[]` | Optional | Array | Filters to apply to the team list. | | `sort` | Optional | String | Sort method to apply to the list (e.g., "newest", "oldest"). | #### Request Example: ```json { "per_page": 10, "page": 1, "sort": "newest", "filters": { "province": "Tehran", "city": "Pardis" } } ``` #### Response Example: ```json { "status": true, "message": "success!", "data": { "data": [ { "id": 2, "owner": { "id": 2, "name": "Maggie Davis", "email": "jonathan.purdy@example.com", "username": "beatty.elta" }, "name": "Langosh Group", "image": "https://via.placeholder.com/640x480.png/0088ee?text=business+nam", "is_personal": 0, "is_active": 1, "location": { "province": { "id": 31, "name": "یزد" }, "city": { "id": 82, "name": "دیلم" } }, "created_at": "2024-09-11T16:17:27.000000Z" }, { "id": 3, "owner": { "id": 4, "name": "Verner Monahan", "email": "megane.wolf@example.net", "username": "rigoberto.walker" }, "name": "Beatty Group", "image": "https://via.placeholder.com/640x480.png/003344?text=business+ex", "is_personal": 0, "is_active": 1, "location": { "province": { "id": 1, "name": "آذربایجان شرقی" }, "city": { "id": 310, "name": "آشتیان" } }, "created_at": "2024-09-11T16:17:27.000000Z" } ], "links": { "first": "http://127.0.0.1:8000/api/v1/team/list?page=1", "last": "http://127.0.0.1:8000/api/v1/team/list?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "path": "http://127.0.0.1:8000/api/v1/team/list", "per_page": 10, "to": 2, "total": 2 } } } ``` --- ### 2. Show Team (Single) - **Endpoint**: `POST /api/v1/team/show` - **Description**: Retrieves the details of a specific team by its ID. - **Authentication**: No - **Permissions**: User #### Request Parameters: | Parameter | Required/Optional | Type | Description | |-----------|-------------------|---------|---------------------| | team_id | Required | Integer | The ID of the team. | #### Request Example: ```json { "team_id": 1 } ``` #### Response Example: ```json { "status": true, "message": "success!", "data": { "id": 2, "owner": { "id": 2, "name": "Maggie Davis", "email": "jonathan.purdy@example.com", "username": "beatty.elta" }, "name": "Langosh Group", "image": "https://via.placeholder.com/640x480.png/0088ee?text=business+nam", "is_personal": 0, "is_active": 1, "location": { "province": { "id": 31, "name": "یزد" }, "city": { "id": 82, "name": "دیلم" } }, "created_at": "2024-09-11T16:17:27.000000Z" } } ``` --- ### 3. List Team Advertisements - **Endpoint**: `POST /api/v1/team/advertises` - **Description**: Retrieves a list of advertisements belonging to a specific team. - **Authentication**: No - **Permissions**: User #### Request Parameters: | Parameter | Required/Optional | Type | Description | |-----------|-------------------|---------|-------------------------------------------------| | team_id | Required | Integer | The ID of the team to retrieve it's advertises. | #### Request Example: ```json { "team_id": 1 } ``` #### Response Example: ```json { "status": true, "message": "success!", "data": { "team_id": "1", "advertises": [ { "id": 1, "advertise_type_id": 1, "type": "supply", "title": "Advertisement title", "price": "100000", "is_new": true, "status": "review", "location": { "province": { "id": 1, "name": "آذربایجان شرقی" }, "city": { "id": 1, "name": "آذرشهر" } }, "images": [ { "name": "VBPCyRi7NVhf06B.png", "path": "http://127.0.0.1:8000/upload/VBPCyRi7NVhf06B.png", "type": "png" }, { "name": "hRJvL3lqfiCZCYC.png", "path": "http://127.0.0.1:8000/upload/hRJvL3lqfiCZCYC.png", "type": "png" } ], "badges": null, "attributes": null, "created_at": "2024-09-12T08:13:13.000000Z", "updated_at": "2024-09-12T08:13:13.000000Z" }, { "id": 2, "advertise_type_id": 2, "type": "supply", "title": "Advertisement title", "price": "100000", "is_new": true, "status": "published", "location": { "province": { "id": 1, "name": "آذربایجان شرقی" }, "city": { "id": 1, "name": "آذرشهر" } }, "images": null, "badges": null, "attributes": null, "created_at": "2024-09-12T08:15:39.000000Z", "updated_at": "2024-09-12T08:15:39.000000Z" } ] } } ``` --- ## Team Membership **NOTICE: This part is NOT completed yet!** The Team Membership API provides endpoints to manage team memberships, including inviting users to join a team, viewing team members, and removing members from a team. ### 1. Invite User to Team **Endpoint:** `POST /team/invite` **Description:** Sends an invitation to a user to join a specific team via email. Requires authentication. **Request Parameters:** | Parameter | Required/Optional | Type | Description | |-----------|-------------------|---------|-------------------------------| | team_id | Required | Integer | The ID of the team. | | user_id | Required | Integer | The ID of the user to invite. | **Request Example:** ```json { "team_id": 1, "user_id": 2 } ``` **Response Example:** ```json { "status": "success", "message": "Invitation sent successfully.", "data": { "user_id": 2, "link": "https://api.example.com/team/join/token_123456" } } ``` --- ### 2. Join Team **Endpoint:** `GET /team/join/{token}` **Description:** Allows a user to join a team using the provided invitation token. Requires authentication. **Request Parameters:** | Parameter | Required/Optional | Type | Description | |-----------|-------------------|--------|-----------------------| | token | Required | String | The invitation token. | **Request Example:** ``` GET /team/join/token_123456 ``` **Response Example:** ```json { "status": "success", "message": "You have successfully joined the team." } ``` --- ### 3. Leave Team **Endpoint:** `POST /team/leave` **Description:** Allows a user to leave a specific team. Requires authentication. **Request Parameters:** | Parameter | Required/Optional | Type | Description | |-----------|-------------------|---------|---------------------| | team_id | Required | Integer | The ID of the team. | **Request Example:** ```json { "team_id": 1 } ``` **Response Example:** ```json { "status": "success", "message": "You have successfully left the team." } ``` ---