Misty API 包含以下组成部分:

  1. 一组REST风格的资源
  2. 描述资源的属性

Misty API 地址是:

http://api.misty.smeshlink.com

API 资源

Misty API 资源包括:Feeds,Entries,Keys,Triggers,每种资源拥有各自特定的属性。下表列出了通过 Misty API 可以进行的操作。

NOTE: 如果使用 Misty API 时没有指定数据类型——JSON,XML或CSV——则默认使用JSON格式进行数据传输。

Feeds,Entries

资源 操作 数据格式 示例URL 请求方法 返回值
Feeds 读取 json, xml, csv http://api.misty.smeshlink.com/feeds/

GET 所有Feed,包括元数据以及子Feed。
Feeds 查询 json, xml, csv http://api.misty.smeshlink.com/feeds/
feed_path?range
GET 指定Feed,包含指定范围内的历史数据。
Feeds 更新 json, xml, csv http://api.misty.smeshlink.com/feeds/
feed_path
PUT HTTP头
Feeds 删除 http://api.misty.smeshlink.com/feeds/
feed_path?range
DELETE HTTP头
Entries 读取 json, xml, csv http://api.misty.smeshlink.com/feeds/
feed_path@key
GET 指定Entry数据
Entries 更新 json, xml, csv http://api.misty.smeshlink.com/feeds/
feed_path@key
PUT HTTP头
Entries 删除 http://api.misty.smeshlink.com/feeds/
feed_path@key
DELETE HTTP头

Keys,Triggers

// TO DO

API 资源属性

下表列出了 Misty API 资源的各项属性:

Feeds

表示一个设备或数据源,包含以下属性。

属性 说明 必填 可配置
Name 名称,唯一标识符
Title 标题,描述性名称
Description 说明文字
Private 是否为私有资源
Hidden 是否为隐藏资源
Tags 标签,以逗号分割,作为描述Feed的元数据
Website 与Feed相关的网站地址,如作者主页
Email 与Feed相关的联系邮箱

Entries

表示键-值形式的数据项,其中Key和At属性为二选一属性,时间型数据具有At属性,非时间型(泛型)数据具有Key属性。

属性 说明 必填 可配置
Key 键,唯一标识符 是*
At 时间,唯一标识符 是*
Value

Locations

属性 说明 必填 可配置
name 位置名称
disposition 表示位置是移动的或是固定的
lat 纬度
lon 经度
ele 海拔
domain [physical, virtual]
exposure [indoor, outdoor]
waypoints 历史位置轨迹。历史位置不能手动修改,当位置信息改变时,Misty将自动记录历史位置。

Waypoints

属性 说明 必填 可配置
at 位置变更时间 N/A
lat 纬度 N/A
lon 经度 N/A
ele 海拔 N/A

Triggers

// TO DO

Keys

// TO DO

查询历史数据

查询指定范围内的历史数据。

示例 http://api.misty.smeshlink.com/feeds/feed_path?range
格式 json, xml, csv
方法 GET

其中,range可以为:

  • start=timestamp
  • end=timestamp
  • duration=seconds
  • start=timestamp&end=timestamp
  • start=timestamp&duration=seconds
  • end=timestamp&duration=seconds

timestamp是以ISO 8601格式表示的时间,例如:2012-05-20T16:03:29Z

seconds是以为单位的时间单元。

其他可以使用的参数有:

参数 说明 示例
limit limit=1000

API调用示例

请求
参数
Method GET
API Endpoint http://api.misty.smeshlink.com/feeds/feed_path?range
请求头
X-ApiKey API_KEY_HERE
数据
This request does not require body data
响应
参数
Status Code 200 OK
数据
{
  "name" : "SeaBo-01A4B1D5150000C0",
  "title" : "Seabo",
  "status" : "live",
  "created" : "2013-03-11T12:14:14.4707791Z",
  "updated" : "2013-03-11T13:09:32.6911149Z",
  "keyType" : "none",
  "valueType" : "none",
  "location" : {
    "domain" : "physical",
    "disposition" : "fixed",
    "exposure" : "indoor"
  },
  "unit" : { }
}
<xfml>
  <feed>
    <name>SeaBo-01A4B1D5150000C0</name>
    <title>Seabo</title>
    <status>live</status>
    <created>2013-03-11T04:14:14.4707791Z</created>
    <updated>2013-03-11T05:09:32.6911149Z</updated>
    <keyType>none</keyType>
    <valueType>none</valueType>
    <tag>SeaBo</tag>
    <location domain="physical" disposition="fixed" exposure="indoor" />
    <unit />
  </feed>
</xfml>
This method doesn't support this data format.

身份认证

API Key认证

API Key用来授权通过API对用户的设备、数据等资源的操作。可以通过两种方式使用API Key:请求头或请求参数。

  • 请求头(HTTP header建议

    X-ApiKey: YOUR_API_KEY_HERE
  • 请求参数(request parameter

    http://api.misty.smeshlink.com/feeds?key=YOUR_API_KEY_HERE

相应的示例GET请求如下:

GET /feeds/myfeed.xml HTTP/1.1
X-ApiKey: YOUR_API_KEY_HERE

或者:

GET /feeds/myfeed.xml?key=YOUR_API_KEY_HERE HTTP/1.1

Basic认证

Basic认证使用用户名与密码进行授权。

注意! 使用Basic认证可能使您的帐户面临风险

GET /feeds/myfeed.xml HTTP/1.1
Authorization: BASIC YOUR_USERNAME_PASSWORD

可访问性

Feed可访问性分为三种:Public,Private和Hidden。通过修改Feed的“private”和“hidden”属性,可以配置是否允许其他人访问Feed数据。

  • 当Feed为Private状态时,只有所有者和授权用户可以访问,并且不会出现在Misty在线目录中。
  • 当Feed为Hidden状态时,除了具有Private的特性,只能通过唯一路径访问,不会出现在任何形式的查询结果中。
  • 当Feed为Public状态时,Feed和它的数据可以被所有用户访问。

创建

创建Feed

示例 http://api.misty.smeshlink.com/feeds
格式 xml, json
方法 POST
返回 HTTP 201 Created
URL of the newly created feed in headers

对该URL的一个HTTP POST请求将为您创建一个新的Feed。

新创建的Feed的地址包含在响应的Location头中。

请求
参数
Method POST
API Endpoint http://api.misty.smeshlink.com/feeds
请求头
X-ApiKey API_KEY_HERE
数据
{
  "name" : "SeaBo-01A4B1D5150000C0",
  "title" : "Seabo",
  "status" : "live",
  "created" : "2013-03-11T12:14:14.4707791Z",
  "updated" : "2013-03-11T13:09:32.6911149Z",
  "keyType" : "none",
  "valueType" : "none",
  "location" : {
    "domain" : "physical",
    "disposition" : "fixed",
    "exposure" : "indoor"
  },
  "unit" : { }
}
<xfml>
  <feed>
    <name>SeaBo-01A4B1D5150000C0</name>
    <title>Seabo</title>
    <status>live</status>
    <created>2013-03-11T04:14:14.4707791Z</created>
    <updated>2013-03-11T05:09:32.6911149Z</updated>
    <keyType>none</keyType>
    <valueType>none</valueType>
    <tag>SeaBo</tag>
    <location domain="physical" disposition="fixed" exposure="indoor" />
    <unit />
  </feed>
</xfml>
This method doesn't support this data format.
响应
参数
Status Code 201 Created

读取数据

罗列Feed

示例 http://api.misty.smeshlink.com/feeds
格式 json, xml, csv
方法 GET
返回 feed列表

返回当前认证用户身份能够查看的所有顶级feed列表,默认分页大小为20。

可以使用以下参数进行条件查询:

参数 说明 示例
p 指定查看页数,默认为1。 http://api.misty.smeshlink.com/feeds?p=3
n [1, 1000],指定每页结果数量,默认为20。 http://api.misty.smeshlink.com/feeds?n=10
content ('full' | 'summary'),表示结果集形式,full表示返回feed及其子feed信息,summary表示仅返回当前feed信息,默认为full。 http://api.misty.smeshlink.com/feeds?content=summary
status ('live' | 'frozen' | 'all'),查询feed状态,默认为all。 http://api.misty.smeshlink.com/feeds?status=frozen
order ('created' | 'updated'),指定返回结果排序字段。 http://api.misty.smeshlink.com/feeds?order=updated
desc (true | false),指定返回结果排序顺序,true表示逆序排序,false表示顺序排序,默认为false。 http://api.misty.smeshlink.com/feeds?order=updated&desc=true
// TODO
// TODO
// TODO

查看Feed

示例 http://api.misty.smeshlink.com/feeds/myfeed
格式 json, xml, csv
方法 GET
返回 feed列表

返回指定feed信息及其最新数据。

// TODO
// TODO
// TODO

删除数据

删除Feed

删除指定的Feed及其子Feed。

警告!该操作不能恢复

请求
参数
Method DELETE
API Endpoint http://api.misty.smeshlink.com/feeds/feed_path
请求头
X-ApiKey API_KEY_HERE
数据
This request does not require body data
响应
参数
Status Code 204 No Content
响应头
No Headers
数据
This response does not contain body data