codelab-adapter增加REST API

Built By Developers, For Developers.

前言

codelab-adapter希望构建开发者生态。

所以我们关注开放性, 在这方面我们做了不少工作:

增加REST API正是出于提高开放性的考虑,以适应更多使用场景。

codelab相信一个好的工具,应该是灵活的,工具的作者无法穷尽使用场景,尤其当它是一个创造性工具的时候。如果我们我们宣称我们已经打造了一个完整的封闭生态,意味着这个工具支持的创造也十分有限。

有黑客精神的开发者要问了: "说了半天开放性,那你们源码究竟什么时候开源? 对于我们这些黑客来说,破解它虽不难吧,但你知道的,麻烦多在破解之后,读一堆注释不清晰的源码,不是什么愉快的经历,尤其是它还一直在迭代更新。如果codelab-adapter能主动公开源代码,并附以清晰的注释和文档,将更容易赢得我们尊重"

别急别急,我们也认同开源不是甩出一堆糟糕的源码,它需要清晰的注释、完整的文档,以及一群热情的开发者。就像Django/Keras/Home Assistant这些社区所做的,而Scratch在开源这块做得并不理想。

codelab-adapter目前迭代更新很快,在realktalk协议发布之后,我们将迎来一次大更新,以实现该协议,因为dynamicland试图打造的用以支持创造的环境,也正是codelab所追求的星辰大海。在这个里程碑之后,codelab-adapter将正式发布v1.0版本,此后codelab-adapter将趋于稳定,那时我们将开源所有的源代码。

codelab是一个非营利组织,开放是我们追求的目标之一。

REST API

REST API已经内置于codelab-adapter最新版本中。

架构图说起。从架构可以看出,codelab-adapter此前对外只提供一个服务: websocket服务, 意味着与codelab-adapter的所有通信,都需要构建websocket通道。

如果开发者只是想从网页或本地应用给codelab-adapter发送一条信息,以控制硬件/IoT/AI,http请求有时候是更轻量和简易的选择。这是Home Assistant给我们的启发。

于是我们构建了REST API。

使用方式

由于codelab-adapter围绕消息设计,所以我们只要提供一个用以发送消息的API即可支持强大的交互。

我们演示一个最简单的例子。

运行codelab-adapter的extension_eim插件,观察来自外部的eim消息:tail -f ~/codelab_adapter/info.log|grep extension_eim

发送一条eim消息

curl -X POST -H "Content-Type: application/json" \
    -d '{"topic": "eim","payload":"hello world"}' \
    https://codelab-adapter.codelab.club:12358/api/message

当然你也可以使用任何编程语言(Python/Nodejs/Java/C++) 来发送http请求,展示一个Python的例子:

import requests
url = "https://codelab-adapter.codelab.club:12358/api/message"
data = {"topic": "eim","payload":"hello world"}
r = requests.post(url, json=data,verify=False)
print(r.json())

注意消息的方向

使用REST API,消息从website(blockly/Scratch) / local app(Python/Nodejs/Java/C++) 流向 codelab-adapter

在网站中使用

开发者可以使用Ajax与codelab-adapter交互!

var xhr = new XMLHttpRequest();
var url = "https://codelab-adapter.codelab.club:12358/api/message"
xhr.open("POST", url, true);
var sendData = {topic: "eim", payload: "hello"};
xhr.setRequestHeader('content-type', 'application/json');
xhr.send(JSON.stringify(sendData));

codelab-adapter的最新版本(0.7.0)已支持跨域访问REST API,开发者可以在web应用里同时使用websocket/Ajax与codelab-adapter交互!

参考




Fork me on GitHub