# Incubated Project API

## Project API Documentation

### Introduction

This document describes the API routes for managing project data. The API supports creating, modifying, deleting, and retrieving project information. Authentication is required for creating, modifying, and deleting projects, while retrieving project information is accessible without authentication.

#### Base URL

The base URL for all endpoints is: <https://paal-ecosystem-backend.onrender.com>

### Routes

#### Create a New Project

* **URL**: `/project/new`
* **Method**: `POST`
* **Authentication Required**: Yes
* **Request Parameters**:
  * `name`: Name of the project (required)
  * `about`: Description of the project (required)
  * `growth`: Growth metrics of the project (optional)
  * `file`: Image file representing the project (optional)
* **Request Example**:

  ```json
  {
    "name": "Project Alpha",
    "about": "This project focuses on AI development.",
    "growth": 20
  }
  ```
* **Response**:
  * **Success**: `{ "status": true, "id": "generated-project-id" }`
  * **Failure**:
    * Missing parameters: `{ "status": false, "error": "Missing parameters" }`
    * File too large: `{ "status": false, "error": "File too large", "MAX_SIZE": 1048576 }`
    * Wrong file type: `{ "status": false, "error": "Wrong file type", "expecting": "image", "sent": "file/type" }`
    * Internal server error: `{ "status": false, "error": "Internal server error" }`

#### Modify Project Data

* **URL**: `/project/save`
* **Method**: `POST`
* **Authentication Required**: Yes
* **Request Parameters**:
  * `projectId`: ID of the project to be modified (required)
  * `name`: New name of the project (optional)
  * `about`: New description of the project (optional)
  * `growth`: Updated growth metrics (optional)
  * `file`: New image file representing the project (optional)
* **Request Example**:

  ```json
  {
    "projectId": "existing-project-id",
    "name": "Updated Project Alpha",
    "about": "Updated description of the project."
  }
  ```
* **Response**:
  * **Success**:

    ```json
    { 
      "status": true, 
      "data": {
        "name": "Updated Project Alpha",
        "about": "Updated description of the project.",
        "growth": 20,
        "file": "url/to/new/file"
      } 
    }
    ```
  * **Failure**:
    * Missing parameters: `{ "status": false, "error": "Missing parameters", "params": "projectId" }`
    * No modifiable fields: `{ "status": false, "error": "No modifiable fields" }`
    * Project does not exist: `{ "status": false, "error": "Project does not exist" }`
    * File too large: `{ "status": false, "error": "File too large", "MAX_SIZE": 1048576 }`
    * Internal server error: `{ "status": false, "error": "Internal server error" }`

#### Delete Project Data

* **URL**: `/project/delete`
* **Method**: `POST`
* **Authentication Required**: Yes
* **Request Parameters**:
  * `projectId`: ID of the project to be deleted (required)
* **Request Example**:

  ```json
  {
    "projectId": "existing-project-id"
  }
  ```
* **Response**:
  * **Success**: `{ "status": true }`
  * **Failure**:
    * Missing parameters: `{ "status": false, "error": "Missing parameters", "expecting": "projectId" }`
    * Project does not exist: `{ "status": false, "error": "Project does not exist" }`

#### Retrieve Project Data

* **URL**: `/project`
* **Method**: `GET`
* **Authentication Required**: No
* **Request Parameters**:
  * `projectId`: ID of the project to be retrieved (required)
* **Request Example**:

  ```json
  /project?projectId=<PROJECT_ID>
  ```
* **Response**:
  * **Success**:

    ```json
    { 
      "status": true, 
      "data": {
        "name": "Project Alpha",
        "about": "This project focuses on AI development.",
        "file": "url/to/file",
        "roi": 15,
        "data": {}
      } 
    }
    ```
  * **Failure**:
    * Missing parameters: `{ "status": false, "error": "Missing parameters", "expecting": "projectId" }`
    * Project does not exist: `{ "status": false, "error": "Project does not exist" }`

#### Retrieve All Projects

* **URL**: `/project/all`
* **Method**: `GET`
* **Authentication Required**: No

**Request Parameters**

* `sort`: Optional. Sort order of the results. Can be `asc` (ascending) or `desc` (descending). Default is `asc`.
* `num`: Required. Number of projects to retrieve. Can be `all` to retrieve all projects or a specific number.

**Request Example**

```http
GET /project/all?sort=desc&num=10
```

**Example Request Using cURL**

```sh
curl -X GET 'https://api.example.com/project/all?sort=desc&num=10'
```

#### Response

**Success Response**

* **Status**: `200 OK`
* **Body**:

  ```json
  {
    "status": true,
    "data": [
      {
        "name": "Project Alpha",
        "about": "This project focuses on AI development.",
        "file": "url/to/file",
        "date": 1682323200000,
        "roi": 15,
        "data": {}
      },
      {
        "name": "Project Beta",
        "about": "This project focuses on blockchain technology.",
        "file": "url/to/file",
        "date": 1682409600000,
        "roi": 15,
        "data": {}
      }
      // Additional projects...
    ]
  }
  ```

**Failure Response**

* **Status**: `400 Bad Request`
* **Body** (Missing `num` parameter):

  ```json
  {
    "status": false,
    "error": "Missing parameters",
    "expecting": "num"
  }
  ```

#### Search Projects

* **URL**: `/project/search`
* **Method**: `GET`
* **Authentication Required**: No

**Request Parameters**

* `sort` (optional): Sort order of the results. Can be `asc` (ascending) or `desc` (descending). Default is `asc`.
* `num` (optional): Number of projects to retrieve. Can be `all` to retrieve all projects or a specific number.
* `key` (required): The field to search within the projects.
* `value` (required): The value to search for in the specified field.

**Request Example**

```http
GET /project/search?key=name&value=example
```

**Example Request Using cURL**

```sh
curl -X GET 'https://paal-ecosystem-backend.onrender.com/project/search?key=name&value=example'
```

### Response

The response will include an array of project data objects matching the search criteria, or an empty array if no projects match the search.

Each project data object contains the following fields:

* `projectId`: ID of the project.
* `name`: Name of the project.
* `about`: Description or details about the project.
* `file`: URL or path to project file.
* `growth`: Growth indicator of the project.
* `date`: Date of the project.
* `roi`: Return on investment value.
* `data`: Additional data related to the project.

### Example Response

```json
{
  "status": true,
  "data": [
    {
      "projectId": "project-id-1",
      "name": "Example Project 1",
      "about": "This is an example project.",
      "file": "https://example.com/project1",
      "growth": 0.25,
      "date": 1653700145000,
      "roi": 15,
      "data": {}
    },
    {
      "projectId": "project-id-2",
      "name": "Example Project 2",
      "about": "Another example project.",
      "file": "https://example.com/project2",
      "growth": 0.5,
      "date": 1653700145000,
      "roi": 15,
      "data": {}
    }
  ]
}
```

### Error Responses

* If required parameters (`key` and `value`) are missing:

  ```json
  {
    "error": "Missing parameters",
    "params": "Key, Value"
  }
  ```
* If no projects match the search criteria:

  ```json
  {
    "status": true,
    "data": []
  }
  ```
