兼容型API（Legacy API）
=======================================

DawnMedical的IoT设计正处于反复迭代的过程中。API的IP、端口、形式都会发生各种变化。为了在一段时间内保证第三方合作伙伴的要求，旧版API会暂时继续运行，但是会根据需要逐渐迁移到新版API。

===========
背景介绍
===========

DawnMedical的IoT应用设计初期并没有确立以RESTFul Web API作为整合第三方应用和移动APP的设计策略。

为了回应第三方合作伙伴的要求，DawnMedical IoT服务器产生了最初版本的Web API。此时，Web API并没有按照行业中通行的最佳实践进行设计，仅仅是简单的JSON Web API。

目前，DawnMedical IoT应用分解为两个云服务器：

#. IoT Device Server，设备云，负责设备接入、数据采集、存储、转换、统计、分析和可视化；
#. IoT Application Web Server，业务应用云、负责业务逻辑、授权和操作；
  
IoT Device Server 和 Application Server之间采用JSON格式的Web API整合。IoT Device Server与其他服务器、APP间也采用同样的Web API接口。

-----------
现有特性
-----------

#. API支持呼吸机和血氧模块的物理量采集：数据采集含实时周期和呼吸周期数据流、日报表数据；
#. 以TCP长连接接入呼吸机；
#. 支持5秒钟实时数据快照；
#. 支持呼吸周期数据保存；
#. 支持XML格式数据导出；
#. 支持设备登录情况导出；
#. 数据可视化支持。

-----------
变更计划
-----------

#. 转换API端口，从现有8888转换到80（HTTP）或443（HTTPS）；
#. 配合设备端升级，将系统架构从TCP长连接升级到MQTT，使用TLS和设备级Topic授权；
#. 保留TCP长连接，升级安全算法；
#. 设备抽象化，以支持更多种类设备接入，引入平台ID以取代设备串号；
#. OAuth/OpenID provider/subscriber整合，以支持多种设备和使用者账号；
#. 将MQTT作为主要数据分享手段，淡化API的数据分享使用；
#. JSON数据结构变化，将realtime, period, daily等数据统一封装在data，并利用error给出错误信息。
#. 其他变更。

以上进行中的变更，或多或少都会对第三方API接入产生影响。

==============
在线设备列表
==============
URI::

    http://www.dawnmed.net/json/v1/devices

列出所有当前在线设备（呼吸机）的串号、IP地址和端口。

返回值::

    {"devices": []}

或::

    {
      "devices": [
        "A2H470014:180.175.138.44:4114", 
        "None:180.175.138.44:28857", 
        "None:180.175.138.44:28860", 
        "A2H470031:180.175.138.44:5503", 
        "A2H470027:180.175.138.44:4112", 
        "A2F900012:180.175.138.44:4102", 
        "A1H470031:180.175.138.44:4128", 
        "A1H470029:180.175.138.44:4118"
      ]
    }

==============
呼吸实时数据
==============
URI::

    http://www.dawnmed.net/json/v1/realtime/<devSNR>
    http://www.dawnmed.net/json/v1/realtime2/<devSNR>

列出当前设备号下所有实时数据，两者区别在于输出JSON格式不同。推荐使用realtime2格式。

返回值::

    {"realtime": []}

或::

    {"realtime": 
        [{"flow": [25, 21, 18, 16, 16, 16, 15, 15, 15, 15], 
            "kpr": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 
            "press": [11.2, 7.6, 4.8, 4.6, 4.6, 4.4, 4.4, 4.4, 4.0, 4.2], 
            "sao2": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 
            "time": "1467672007.772"}, 
        {"flow": [14, 14, 14, 13, 13, 13, 13, 13, 13, 13], 
            "kpr": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 
            "press": [3.8, 3.8, 3.8, 3.6, 3.6, 3.4, 3.4, 3.4, 3.2, 3.2], 
            "sao2": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 
            "time": "1467672008.273"}, 
        {"flow": [14, 14, 14, 14, 14, 14, 15, 14, 14, 14], 
            "kpr": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 
            "press": [4.0, 4.0, 4.0, 4.0, 4.0, 4.0, 4.0, 4.0, 3.8, 3.8], 
            "sao2": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 
            "time": "1467672008.773"}, 
        {"flow": [14, 14, 14, 14, 14, 14, 14, 14, 14, 14], 
            "kpr": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 
            "press": [3.8, 4.0, 4.0, 3.8, 4.0, 3.8, 3.8, 4.0, 4.0, 3.8], 
            "sao2": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 
            "time": "1467672009.274"}, 
        {"flow": [14, 14, 14, 14, 15, 14, 15, 14, 14, 14], 
            "kpr": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 
            "press": [4.0, 4.0, 4.0, 3.8, 3.8, 4.0, 4.0, 4.0, 4.0, 4.0], 
            "sao2": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 
            "time": "1467672009.773"}, 
        {"flow": [14, 14, 14, 14, 14, 14, 14, 14, 14, 14], 
            "kpr": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 
            "press": [3.8, 4.0, 4.0, 4.0, 4.0, 4.0, 4.0, 3.8, 4.0, 4.0], 
            "sao2": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 
            "time": "1467672010.272"}]
    }

其中APP或服务器可以通过此接口在UI上进行实时绘图。物理量参数说明：

.. csv-table:: 物理量说明
   :header: "英语","汉语","范围","单位","备注"
   :widths: 10,12,10,10,40

   "flow","流量","0~51","l/min","呼吸空气流量"
   "press","压力","0~255","cmH2O","呼吸压力"
   "sao2","血氧","0~100","%","夹指式血氧模块血氧指数"
   "kpr","脉率","0~255","/min","每分钟脉率"

每个物理量数组中包含10个数值，代表在0.5秒内的10个采样点。拟增加采样周期参数。

===============
呼吸周期数据
===============

即用户睡眠时的呼吸周期数据。该数据不是定期采样的周期数据，采样时间/频率随着用户呼吸而变化。

URI::

    http://www.dawnmed.net/json/v1/period/<devSNR>
    http://www.dawnmed.net/json/v1/period2/<devSNR>/<count> （count<200，为数据库n个呼吸周期数据快照）
    http://www.dawnmed.net/json/v1/period3/<devSNR>/<start>/<stop>  （start/stop时间格式：yyyy-mm-dd,HH:MM:SS）

列出当前设备号下所有周期数据，三者区别在于固定长度，可变长度和起始位置参数。推荐使用第三种。

返回值::

    {"period": []}

或::

    {"period": 
        [{"alarm": 0, "cql": 0, "epap": 4, "fengy": 12, "hxpl": 10, "indient": 64, "ipap": 12, "lql": 14, "my": 4, "pjyl": 52, "ramp": 64, "recId": 15345510, "time": 1467604801.0}, 
        {"alarm": 0, "cql": 0, "epap": 4, "fengy": 12, "hxpl": 10, "indient": 64, "ipap": 12, "lql": 14, "my": 4, "pjyl": 52, "ramp": 64, "recId": 15345515, "time": 1467604807.0}, 
        {"alarm": 0, "cql": 0, "epap": 4, "fengy": 12, "hxpl": 10, "indient": 64, "ipap": 12, "lql": 14, "my": 3, "pjyl": 52, "ramp": 64, "recId": 15345520, "time": 1467604813.0}, 
        {"alarm": 0, "cql": 0, "epap": 4, "fengy": 12, "hxpl": 10, "indient": 64, "ipap": 12, "lql": 14, "my": 3, "pjyl": 52, "ramp": 64, "recId": 15345527, "time": 1467604819.0}]
    }

.. csv-table:: 物理量说明
   :header: "英语","汉语","范围","单位","备注"
   :widths: 10,12,10,10,40

   "cql","潮气量","0~2550","ml","用户使用中的监测潮气量，即吸气量"
   "epap","呼气压力","2~20","cmH2O","呼气时提供较低的压力支持(EPAP)，用于控制用户PEEP值"
   "fengy","峰值压力","0~255","cmH2O","最高呼吸压力数值"
   "hxpl","呼吸频率","3~255","bpm","每分钟呼吸次数"
   "ipap","吸气压力","4~25","cmH2O","吸气时提供较高的压力支持(IPAP)，用于控制用户的最大吸气压力"
   "lql","漏气量","0~100","l/min","每分钟泄漏气量"
   "my","呼气末压","2~20","cmH2O","控制呼吸或辅助呼吸时，于呼吸末期在呼吸道保持的正压，监测PEEP"
   "pjyl","平均压力","0~25.5","cmH2O","单次呼吸周期压力平均值"
   "indient","保留标志位","N/A","N/A","暂无实际意义"
   "ramp","保留标志位","N/A","N/A","暂无实际意义"
   "time","时间戳","N/A","s","UNIX时间戳，精确到ms"

“alarm”报警数据为枚举数值，长度1个字节。枚举含义为：

#. 0x00：无报警。
#. 0x01：低呼吸频率
#. 0x02: 高呼吸频率
#. 0x03: 电量不足
#. 0x04：低压报警
#. 0x05：低漏气量
#. 0x06：高漏气量
#. 0x07：高压报警
#. 0x08：电量过低
#. 0x09：湿化器报警
#. 其他值：保留

==============
设备使用日报表
==============
URI::

    http://www.dawnmed.net/json/v1/usage2/<devSNR>/<date> （日期格式：yyyy-mm-dd）

返回值::

    {
      "data": {}, 
      "errno": -1, 
      "error": "not available"
    }

或::

    {
      "data": {
        "AHI": 0.0, 
        "AI": 0.0, 
        "HI": 0.0, 
        "P95": 80, 
        "duration": 437, 
        "frequency": 17, 
        "leak": 14, 
        "press": 71, 
        "recId": 11512, 
        "tidal": 34
      }, 
      "errno": 0, 
      "error": "succ"
    }

.. csv-table:: 物理量说明
   :header: "英语","汉语","范围","单位","备注"
   :widths: 10,12,10,10,40

   "duration","使用时长","12h60m","h:m","病人于前日12:00PM到当日11:59AM间使用时长"
   "frequency","呼吸频率","3~255","bpm","呼吸频率均值"
   "press","呼吸压力","0~25.5","cmH2O","整晚CPAP治疗压力的平均值"
   "leak","漏气量","0~100","l/min","从面具中泄漏的空气量均值，**适当** 数值可以提高用户依从度"
   "tidal","潮气量","0~2550","ml","吸气量均值"
   "AHI","AI+HI","0~255","/h","呼吸暂停与低通量指数值之和"
   "AI","呼吸暂停指数","0~255","/h","每小时睡眠过程中口鼻呼吸气流完全停止10秒以上"
   "HI","低通气量指数","0~255","/h","呼吸气流强度(幅度)较基础水平降低50%以上，并伴有血氧饱和度较基础水平下降大于等于4%"
   "P95","95%压力","0~25.5","cmH2O","95%的时间内呼吸机的工作压力低于某值，即合适的治疗压力"

================
设备登录详情
================
URI::

    http://www.dawnmed.net/json/v1/logbook/<date>/<devSNR>（日期格式：YYYYmmdd）

返回值::

    {
      "snrCode": "A2H470049",
      "logbook": [
      {"durationSession": 2151, "host": "36.62.137.190", "login": 1475123758.0, "logout": 1475125909.0, "port": 43637, "recId": 51573}, 
      {"durationSession": 744, "host": "36.62.137.190", "login": 1475126416.0, "logout": 1475127160.0, "port": 45041, "recId": 51583}, 
      ],
    }


.. csv-table:: 属性说明
   :header: "英语","汉语","范围","单位","备注"
   :widths: 10,12,10,10,40

   "durationSession","使用时长","0~60x60x24","秒","单次登录使用时间"
   "host","设备IP地址","x.x.x.x","N/A","登陆时IP地址"
   "port","设备端口","0~65535","N/A","登陆时端口"
   "login","登入时间","?","ts","主机登陆时间"
   "logout","登出时间","?","ts","主机登出时间"
   "recId","记录ID","?","N/A","数据库记录ID"

==============
XML报表
==============
URI::

    http://www.dawnmed.net/xml/<devSNR>.rss 
    http://www.dawnmed.net/xml/<devSNR>.dw

----------------
更新
----------------

DM是DawnMedical定义的自有XML格式文档，用于桌面应用程序的数据提取。缺点是文件太大。所以在每日批处理中增加了对于压缩XML文档的支持，压缩比为1:10~1:50。

由于设备服务器开始支持呼吸机和血氧仪，原有的数据库结构不再适用。所以从2016/10/01开始，不再支持杜恩原有的呼吸机XML数据格式DW，改为压缩存储的CSV文档。开发者可以利用这些数据进行特定设备的分析，报表生成和后续处理。


================
设备归档汇总
================

用于返回指定日期的设备数据压缩文档：csv.zip。

URI::

    http://www.dawnmed.net/json/v1/archives/<date>/<devSNR>

<date>格式为yyyy-mm-dd，例如2016-12-21。<devSNR>支持通配符。

**更新**

因为该URI过于宽泛，所以中间添加了日期作为限制。同时返回JSON中域名增加为全域名以方便应用开发者使用。


返回值::

    {
      "device": "A1H47003*.csv", 
      "error": 0, 
      "error_code": "OK", 
      "archives": [
        "http://www.dawnmed.net/static/archive/2016/10/02/A1H470038.csv.zip", 
        "http://www.dawnmed.net/static/archive/2016/10/01/A1H470038.csv.zip", 
        "http://www.dawnmed.net/static/archive/2016/10/01/A1H470031.csv.zip"
      ]
    }


.. csv-table:: 属性说明
   :header: "英语","汉语","范围","单位","备注"
   :widths: 10,12,10,10,40

   "device","设备串号","?","N/A","杜恩自定义设备串号，支持通配符查询"


================
设备报告汇总
================

用于返回指定日期的设备使用报告文档：pdf。

URI::

    http://www.dawnmed.net/json/v1/reports/<date>/<devSNR>

<date>格式为yyyy-mm-dd，例如2016-12-21。<devSNR>支持通配符。

**更新**

因为该URI过于宽泛，所以中间添加了日期作为限制。同时返回JSON中域名增加为全域名以方便应用开发者使用。


返回值::

    {
      "archives": [
        "http://www.dawnmed.net/static/pdf/2016/12/20/A2H470016_2016-12-20_Night.pdf", 
        "http://www.dawnmed.net/static/pdf/2016/12/20/A2H470016_2016-12-20_Day.pdf", 
        "http://www.dawnmed.net/static/pdf/2016/12/20/A2H470016_2016-12-20_AllDay.pdf"
      ], 
      "device": "A2H47001*", 
      "error": 0, 
      "error_code": "OK"
    }


.. csv-table:: 属性说明
   :header: "英语","汉语","范围","单位","备注"
   :widths: 10,12,10,10,40

   "device","设备串号","?","N/A","杜恩自定义设备串号，支持通配符查询"

:doc:`index`