# Consentium IoT Sensor Data API — Developer Documentation v1 (depricated)

This API allows the creation, update, retrieval, and management of sensor data associated with various boards. Each board can have multiple sensors with unique data points.

### Base URL

```url
https://consentiumiot.com/api/board/
```

***

## **Authentication**

All API requests require authentication via `sendkey` or `receivekey`, depending on the type of operation (e.g., sending or receiving data). The keys should be included as URL parameters.

### **Request Authentication Parameters:**

* **`sendkey`**: A key used for authenticated operations such as creating or deleting data.
* **`receivekey`**: A key used to retrieve or read data from the board.

***

## **Endpoints Overview**

| HTTP Method | Endpoint          | Description                                                |
| ----------- | ----------------- | ---------------------------------------------------------- |
| **POST**    | `/updatedata`     | Create or update sensor data on a board.                   |
| **GET**     | `/getdata`        | Retrieve all sensor data for a specific board.             |
| **GET**     | `/getdata/recent` | Retrieve the most recent sensor data for a specific board. |

***

## **1. Create or Update Sensor Data (POST)**

### **Endpoint**

```url
POST /updatedata?key=YOUR_SEND_KEY&boardkey=YOUR_BOARD_KEY
```

### **Description**

This API endpoint is used to create new sensor data or update existing sensor data for a specific board. Up to seven sensors can be updated simultaneously for a board. Each sensor has an `info` field (which provides a label or description) and a `data` field (which stores the value for that sensor).

### **URL Parameters**

* `key=YOUR_SEND_KEY` (required): The authentication key used to authorize the creation or update of sensor data.
* `boardkey=YOUR_BOARD_KEY` (required): The unique identifier for the board to which the sensor data will be added.

### **Request Body Format**

The body must include a JSON object with an array of sensors. Each sensor entry contains:

* `info`: A string describing the sensor (e.g., "Temperature", "Humidity").
* `data`: A numeric value representing the data for that sensor.
* `firmwarefirmwareVersion`: A numeric value representing the firmware version for that board.
* `architecture`: A string value representing the board type (e.g. ESP32, ESP8266, GenericPython)

#### **Example Request Body**

```json
{
    "sensors": {
        "sensorData": [
            {
                "info": "Temperature",
                "data": "34.00"
            },
            {
                "info": "Humidity",
                "data": "90.00"
            }
        ]
    },
    "boardInfo": {
        "firmwareVersion": "0.0",
        "architecture": "ESP32"
    }
}
```

### **Response**

* **200 OK**: The sensor data was successfully created or updated.
* **400 Bad Request**: There was an issue with the request (e.g., malformed body, missing parameters).

#### **Example Response**

```json
{
  "message": "Sensor data updated successfully"
}
```

***

## **2. Get All Sensors for a Board (GET)**

### **Endpoint**

```
GET /getdata?receivekey=YOUR_RECEIVE_KEY&boardkey=YOUR_BOARD_KEY
```

### **Description**

This API retrieves all the sensor data associated with a specific board. It returns an array of sensor data, each containing information such as the sensor type (`info`) and its recorded value (`data`).

### **URL Parameters**

* `receivekey=YOUR_RECEIVE_KEY` (required): The authentication key used to retrieve sensor data.
* `boardkey=YOUR_BOARD_KEY` (required): The unique identifier for the board from which the sensor data will be retrieved.

### **Response**

* **200 OK**: A JSON array of sensor data is returned.
* **400 Bad Request**: The request is invalid (e.g., missing or incorrect parameters).

#### **Example Response**

```json
{
  "sensors": [
    {
      "info": "Humidity",
      "data": "230"
    },
    {
      "info": "Temperature",
      "data": "24"
    }
  ]
}
```

***

## **3. Get the Most Recent Sensor Data (GET)**

### **Endpoint**

```
GET /getdata/recent?receivekey=YOUR_RECEIVE_KEY&boardkey=YOUR_BOARD_KEY
```

### **Description**

This API fetches the most recent sensor data entry for a specified board. It is particularly useful for monitoring real-time updates or viewing the latest data points for a board.

### **URL Parameters**

* `receivekey=YOUR_RECEIVE_KEY` (required): The authentication key used to retrieve the most recent sensor data.
* `boardkey=YOUR_BOARD_KEY` (required): The unique identifier for the board from which the most recent sensor data will be retrieved.

### **Response**

* **200 OK**: The most recent sensor data is returned in JSON format.
* **400 Bad Request**: The request is invalid (e.g., missing or incorrect parameters).

#### **Example Response**

```json
{
  "info": "Temperature",
  "data": "24",
  "timestamp": "2024-09-03T12:34:56Z"
}
```

***

## **Error Handling**

The API uses standard HTTP status codes to indicate the success or failure of an API request. Here's a summary of the potential errors:

| Status Code          | Error Message              | Description                                                                                                                                |
| -------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **200 OK**           | Success                    | The request was successful, and the response contains the data requested.                                                                  |
| **400 Bad Request**  | Invalid request            | There was a problem with the request. This could be due to missing required parameters or an invalid request format.                       |
| **401 Unauthorized** | Invalid or missing API key | The provided `sendkey` or `receivekey` is either missing or invalid. Please ensure the key is correct and has the appropriate permissions. |
| **404 Not Found**    | Board not found            | The `boardkey` provided does not match any existing boards. Ensure the board key is correct.                                               |

***

## **Best Practices**

* **Rate Limiting**: Avoid sending too many requests in a short period. Implement proper rate-limiting mechanisms in your application to prevent being throttled.
* **Error Handling**: Always check for non-200 status codes and handle them appropriately in your application (e.g., retry logic, user-friendly error messages).
* **Data Validation**: Ensure that the `info` field in sensor data accurately describes the sensor and that the `data` field contains appropriate numeric values. This ensures consistency and readability when retrieving sensor data later.