---
# System prepended metadata

title: RESTful API
tags: [Columba]

---

---
title: RESTful API
tags: Columba
---

<style>
code.redrose {
  color: #FFFFFF !important ; background-color:#E81E25 ; font-size: 14pt;
}
code.get {
  color: #FFFFFF !important ; background-color:#48cc90 ; font-size: 14pt;
}
   
code.post {
  color: #FFFFFF !important ; background-color:#fca12f ; font-size: 14pt;
}

code.put {
  color: #FFFFFF !important ; background-color:#62afff ; font-size: 14pt;
}
    
code.del {
  color: #FFFFFF !important ; background-color:#f83e3f ; font-size: 14pt;
}
    
code.get_txt {
  color: #000000 !important  ; background-color:#def0d8 ; font-size: 16pt;
}

code.post_txt {
  color: #000000 !important  ; background-color:#fbf9e4 ; font-size: 16pt;
}
    
code.put_txt {
  color: #000000 !important  ; background-color:#d9edf6 ; font-size: 16pt;
}
    
code.del_txt {
  color: #000000 !important  ; background-color:#f2dedf ; font-size: 16pt;
}
</Style>


| 日期       | 版號    | 說明  | 
| ---------- | :--- | --------|
|2023/05/26 | v1.0|初稿|
|2023/10/19 | v1.0|大改|


:::info
[TOC]
:::





# MQTT

## 設備

### 1. 新增設備
:::warning
<code class="post">POST</code><code class="post_txt">/api/v1.0/columba/mqtt/device</code>
:::
:::spoiler

|Request|
|---|
```json=
POST /api/v1.0/columba/mqtt/device HTTP/1.1
Content-Type: application/json
[
    {
        "device_name":"ADAM",
        "ip":"192.168.2.99",
        "port":"",
        "broker_host":"192.168.2.60",
        "broker_port":"1883",
        "broker_username":"touchcloud",
        "broker_password":"touchcloud"
    }
]
```
|Respond|
|---|
```json=
[
    {
        "Result": "Succee",
        "Respond": "Device 'ADAM' is add"
    }
]
```
:::

### 2. 取得設備設定資訊
:::success
<code class="get">GET</code><code class="get_txt">/api/v1.0/columba/mqtt/device</code>
:::

:::spoiler

|Request|
|---|
```json=
Get /api/v1.0/columba/mqtt/device HTTP/1.1
Content-Type: application/json
```
|Respond|
|---|

```json=
{
    "Result": "Succee",
    "Respond": [
        {
            "device_name": "ADAM",
            "ip": "192.168.2.99",
            "port": null,
            "broker": {
                "host": "localhost",
                "port": 1883,
                "username": "touchcloud",
                "password": "touchcloud"
            },
            "points": {},
            "last_time": 1685094563792
        }
    ]
}
```
:::

### 3. 修改設備設定資訊
:::info
<code class="put">PUT</code><code class="put_txt">/api/v1.0/columba/mqtt/device</code>
:::

:::spoiler

|Request|
|---|

```json=
Put /api/v1.0/columba/mqtt/device HTTP/1.1
Content-Type: application/json
[
    {
    "device_name":"ADAM",
    "update_payload":{
        "device_name":"ADAM",
        "ip":"192.168.2.99",
        "port":"",
        "broker_host":"192.168.2.60",
        "broker_port":"1883",
        "broker_username":"zack",
        "broker_password":"zack"
        }
    }
]
```
|Respond|
|---|

```json=
[
    {
        "Result": "Succee",
        "Respond": "Device 'ADAM' is set"
    }
]
```
:::

### 4. 刪除設備
:::danger
<code class="del">DELETE</code><code class="del_txt">/api/v1.0/columba/mqtt/device</code> 
:::

:::spoiler
|Request|
|---|
```jsonld=
DELETE /api/v1.0/columba/mqtt/device HTTP/1.1 
Accept: application/json
["ADAM"]
```

|Response|
|---|
```json=
[
    {
        "Result": "Succee",
        "Respond": "Device 'ADAM' is delete"
    }
]
```
:::

## 點位

### 1. 新增設備點位
:::warning
<code class="post">POST</code><code class="post_txt">/api/v1.0/columba/mqtt/{device_name}/</code>
:::
:::spoiler

|Request|
|---|
```json=
POST /api/v1.0/columba/mqtt/ADAM HTTP/1.1
Content-Type: application/json
[
    {
        "point_name":"DO_0",
        "RW": "R",
        "unit": "",
        "default_value":"off",
        "read_topic":"Advantech/74FE487983F5/data",
        "read_mark_key":"",
        "read_mark_value":"",
        "read_key":"do1",
        "read_is_json_payload":true
    }
]
```
|Respond|
|---|
```json=
[
    {
        "Result": "Succee",
        "Respond": "Point 'DO_0' is add in 'ADAM'"
    }
]
```
:::

### 2. 取得設備點位資訊
:::success
<code class="get">GET</code><code class="get_txt">/api/v1.0/columba/mqtt/{device_name}/</code>
:::

:::spoiler

|Request|
|---|
```json=
Get /api/v1.0/columba/mqtt/ADAM/ HTTP/1.1
Content-Type: application/json
```
|Respond|
|---|

```json=
{
    "Result": "Succee",
    "Respond": [
        {
            "point_name": "DO_0",
            "RW": "R",
            "unit": "",
            "default_value": "off",
            "read_topic": "Advantech/74FE487983F5/data",
            "read_mark_key": "",
            "read_mark_value": "",
            "read_key": "do1",
            "read_is_json_payload": true,
        }
    ]
}
```
:::

### 3. 修改設備點位資訊
:::info
<code class="put">PUT</code><code class="put_txt">/api/v1.0/columba/mqtt/{device_name}/</code>
:::

:::spoiler

|Request|
|---|

```json=
Put /api/v1.0/columba/mqtt/ADAM/ HTTP/1.1
Content-Type: application/json
[
    {
    "point_name":"DO_0",
    "update_payload":{
        "point_name":"DO_0",
        "RW": "R",
        "unit": "",
        "default_value":"on",
        "read_topic":"Advantech/74FE487983F5/data",
        "read_mark_key":"",
        "read_mark_value":"",
        "read_key":"do1",
        "read_is_json_payload":true
        }
    }
]
```
|Respond|
|---|

```json=
[
    {
        "Result": "Succee",
        "Respond": "Point 'DO_0' is set"
    }
]
```
:::

### 4. 刪除設備點位
:::danger
<code class="del">DELETE</code><code class="del_txt">/api/v1.0/columba/mqtt/{device_name}/</code> 
:::

:::spoiler
|Request|
|---|
```jsonld=
DELETE /api/v1.0/columba/mqtt/ADAM/ HTTP/1.1 
Accept: application/json
["DO_0"]
```

|Response|
|---|
```json=
[
    {
        "Result": "Succee",
        "Respond": "Point 'DO_0' is delete"
    }
]
```
:::