デバイスWebAPI設計の進め方

2017/7/14
株式会社ＮＴＴドコモ

Copyright© 2017 NTT DOCOMO, Inc. All rights reserved

1

デバイスWebAPI技術のおさらい

Copyright© 2017 NTT DOCOMO, Inc. All rights reserved2スマートフォンにつながる様々なデバイスの現状
ひとつひとつのデバイスや規格にあわせ、それぞれの環境での開発が必要
様々なデバイス

温度センサー
時計型
デバイス

Android

ネイティブ
アプリ

iPhoneハイブリッドアプリ

Windows

Webアプリ／Webブラウザ

無線LAN
Bluetooth

スマート
家電B規格

BLE
USB

体重計

…

アクション
カメラ
スマートトイ（おもちゃ）

開発

Android
アプリ開発者
iOSアプリ開発者
スクリプト言語
開発者
Webアプリ
開発者

…

心拍数計

デバイスを使いたい開発者

様々な実行環境、開発環
境

…

メガネ型
デバイス

スマート
家電A規格

様々な
通信プロトコル

デバイス毎のSDK,API、仕様等…

Android用
A規格SDK

iOS用
A規格SDK

iOS用
B規格API

Android用
Cデバイス向け
管理アプリ

D規格用
接続仕様

E用クラウド
データ取得API

Copyright© 2017 NTT DOCOMO, Inc. All rights reserved…
3スマートフォンにつながる様々なデバイスの現状
ひとつひとつのデバイスや規格にあわせ、それぞれの環境での開発が必要
様々な通信プロトコル

様々なデバイス

温度センサー
時計型
デバイス

Android

ネイティブ
アプリ

iPhoneハイブリッドアプリ

Windows

Webアプリ／Webブラウザ

Bluetooth
スマート
家電B規格

BLE
USB

体重計

…

スマートトイ（おもちゃ）…
通信の仕組みの違いにあわせた開発が必要

…

心拍数計
アクション
カメラ

使いたい開発者
環境にあわせた作りこみが必要

Android
アプリ開発者

無線LAN

…

メガネ型
デバイス

スマート
家電A規格

そもそもデバイスを作れない

様々な実行環境、開発環
境iOSアプリ開発者

デバイスアクセスが制限された環境

スクリプト言語
開発者
Webアプリ開発者

開発環境の構築が大変

デバイス毎のSDK,API、仕様等
Android用
A規格SDK

iOS用
A規格SDK

iOS用
B規格API

Android用
Cデバイス向け
管理アプリ

D規格用
接続仕様

E用クラウド
データ取得API

Copyright© 2017 NTT DOCOMO, Inc. All rights reserved

色々な仕様を覚えるのが大変…
4

デバイスＷｅｂＡＰＩとは？
デバイスの持つ機能に、共通の記述（ＷｅｂＡＰＩ）でアクセスする仕組みで現状の課題を解決
様々なデバイス機能

様々な通信プロトコル

デバイス１
温度
無線LAN
BluetoothAndroid

ネイティブ
アプリ

Web
iPhoneインターフェース

ハイブリッドアプリ

Windows

BLE

デバイスをどの開発者も 使いたい開発者共通の記述を覚えるだけ

Android
アプリ開発者
iOSアプリ開発者
スクリプト言語
開発者

Webアプリ／Webブラウザ

…

…

USB

…

……

センサー
スマート通知
加速度
画面
家電A規
時計型
格
デバイス
デバイス２
スマート
家電B規
画面
ライト
カメラ
メガネ型
格
デバイス
デバイス３ 心拍数計
アクション
心拍数
通知
カメラ 加速度スマートト
体重計
イ（おもちゃ）
デバイスを機能の集合として表現

様々な実行環境、開発環
境

共通の記述（WebAPI）

スマートフォン
経由での、他の環境からの利用

Webアプリ
開発者

デバイス毎のSDK,API、仕様等
Android用
A規格SDKiOS用
A規格SDK

iOS用
B規格API

Android用

D規格用
接続仕様

E用クラウド
データ取得API

仕組みの違いを違いを意識する
Cデバイス向け
意識する必要なし
必要がなくなる
管理アプリ

Copyright© 2017 NTT DOCOMO, Inc. All rights reserved…
5参考：そもそもＷｅｂＡＰＩとは？
Web API 【 Web Application Programming Interface 】 ウェブAPI
Web APIとは、コンピュータプログラムの提供する機能を外部の別のプログラムから呼び出して利用するための手順・規約（API：Application Programming Interface）の類型の一つで、HTTPなどWebの技術を用いて構築されたもののこと。
IT用語辞典e-words（http://e-words.jp/w/Web_API.html）よりレスポンス

リクエスト
HTTP GET
POST
PUT
DELETE

JSON、XML、HTML、ﾘｿｰｽ(画像データ等)、WebSocket等…

WebAPI（HTTPリクエスト）記述のお作法
・RESTfulという設計思想に従うのが一般的だが、細かいところでは諸説あり
・UpperCamelCase、lowerCamelCase、snake_case
・サブドメインとして表すか、パスとして表すか・バージョン表記（整数、小数、つけるかどうか）・APIの粒度（パスとして表すか、リクエストで送る中身（JSON等）に書くか）

Copyright© 2017 NTT DOCOMO, Inc. All rights reserved

6どうやって実現しているか スマートフォン上で動作する仮想サーバに、スマートフォン内部のIPネットワーク層を経由することで、Webブラウザからでも高度な機能アクセスを実現ネイティブアプリからも同様に利用可能
インターネット上のWebサイト

WebアプリWebアプリ(HTML5+Javascript)
Webアプリ(HTML5+Javascript)(HTML5+Javascript)

IPネットワーク経由で仮想サーバにアクセス

Webブラウザ

デバイスWebAPI
拡張プラグインA
拡張プラグインB
拡張プラグインC

デバイスアクセス要求を各デバイスの制御命令に変換（プラグインで拡張）

仮想サーバ

フレームワーク
ライブラリ
Kernel

IPネットワーク層

Android OS

ネイティブアプリ
として任意の機能が利用可能

デバイス
Copyright© 2017 NTT DOCOMO, Inc. All rights reserved

7Webのトレンドで見た場合※2年前の資料
一般的なWebアプリ（Webブラウザ）
からのデバイス利用、トレンド

Webアプリ(HTML5+Javascript)
ドライバ/Profile相当
ドライバ/Profile相当
ドライバ/Profile相当

デバイスWebAPIでのデバイス利用

Web
アプリ

Python・Ruby等

Web
ブラウザ

スクリプトエンジン

WebブラウザWebエンジン
低レイヤー
デバイスAPI規定
デバイスAPI規定（JavaScript）（JavaScript）
低レイヤーのドライバ

ドライバ/Profile
ドライバ/Profile
ドライバ/Profile

ネイティブ
アプリ

仮想サーバ＋REST API I/F（GotAPIでの規定部分）

デバイスWebAPI
デバイスWebAPI（機能単位のREST
API規定）
デバイスWebAPI（機能単位のREST API規定）（機能単位のREST API規定）

ドライバ/Profile

低レイヤーのドライバ

デバイス
デバイス

最近のWeb規格化の流れ(Extensible Web)

ある意味でｴﾝﾀｰﾌﾟﾗｲｽﾞ開発における最近のｱｰｷﾃｸﾁｬｽﾀｲﾙ
(Micro Services)に近い？

Copyright© 2017 NTT DOCOMO, Inc. All rights reserved

8ブラウザでのデバイスAPIの現状
一般的なWebアプリ（Webブラウザ）からのデバイス利用

Webアプリ(HTML5+Javascript)

カメラ、マイク等の一部機能への対応が若干進む

ドライバ/Profile相当
ドライバ/Profile相当
ドライバ/Profile相当
WebブラウザWebエンジン
低レイヤー
デバイスAPI規定
デバイスAPI規定（JavaScript）（JavaScript）
ドライバ/Profile
ドライバ/Profile
ドライバ/Profile

ChromeブラウザがWebBluetoothを正式サポート開始

低レイヤーのドライバ
デバイス

Webブラウザも限定的にデバイス機能アクセスの範囲が拡大中だが前述の課題は残ったまま
Copyright© 2017 NTT DOCOMO, Inc. All rights reserved

9Webのトレンドから見てデバイスＷｅｂＡＰＩはどうなったか？
一般的なWebアプリ（Webブラウザ）
からのデバイス利用、トレンド

Webアプリ(HTML5+Javascript)
ドライバ/Profile相当
ドライバ/Profile相当
ドライバ/Profile相当

デバイスWebAPIでのデバイス利用

Web
アプリ

Python・Ruby等

Web
ブラウザ

スクリプト
エンジン

WebブラウザWebエンジン
低レイヤー
デバイスAPI規定
デバイスAPI規定（JavaScript）（JavaScript）
低レイヤーのドライバドライバ/Profile
ドライバ/Profile
ドライバ/Profile

ネイティブ
アプリ

仮想サーバ＋REST API I/F（GotAPIでの規定部分）

デバイスWebAPI
デバイスWebAPI（機能単位のREST
API規定）
デバイスWebAPI（機能単位のREST API規定）（機能単位のREST API規定）

ドライバ/Profile

低レイヤーのドライバ

デバイス
デバイス

最近のWeb規格化の流れ(Extensible Web)

ある意味でｴﾝﾀｰﾌﾟﾗｲｽﾞ開発における最近のｱｰｷﾃｸﾁｬｽﾀｲﾙ
(Micro Services)に近い？

Copyright© 2017 NTT DOCOMO, Inc. All rights reserved

10ＷｅｂＡＰＩのトレンド
・サーバレスアーキテクチャ
自前サーバではなく、AWS(Amazon Web Serivce)等のクラウド基盤を活用したサービス設計

・マイクロサービス
一枚板なサービス基盤を作るのではなく、OSといった実行環境や開発環境の違う小さなサービスを組み合わせて一つのサービスを提供する設計。サービス間の環境の違いを吸収してつなげるために、WebAPIが用いられる。

・ＷｅｂＡＰＩ設計の国際標準化
AWSのAPI Gateway等で使われているAPI記述仕様のSwaggerをベースとした標準化が、ﾏｲｸﾛｿﾌﾄ,Google等が立ち上げたOpen API
Initiativeで進行中。
WebAPIのトレンド（API記述の標準化）をデバイスWebAPIでも活用
Copyright© 2017 NTT DOCOMO, Inc. All rights reserved

11

デバイスWebAPIの現状

・デバイスWebAPIでのSwagger仕様の活用
・ローカル環境からクラウド環境への拡張
・ドキュメント整備

Copyright© 2017 NTT DOCOMO, Inc. All rights reserved

12

Ｓｗａｇｇｅｒとは・RESTful APIのドキュメントや、サーバ、クライアントコード、エディタ、またそれらを扱うための仕様(YAML/JSON)などを提供するフレー
ムワーク
・Google、IBM、Microsoft等がOpen API InitiativeというSwagger仕様に基づくWebAPI標準化団体を設立（仕様の名前もSwaggerからOAS：Open API Specificationに）・Amazonは上記団体に入っていないが、AWS API Gatewayでも利用されている

Copyright© 2017 NTT DOCOMO, Inc. All rights reserved13

Ｓｗａｇｇｅｒベースでのモデルファースト開発

デバイスWebAPIでもSwaggerベースでのモデルファーストのフレームワーク提供⇒同一のAPI設計で、様々な環境での機能提供を実現
以前
一般的なアプリ開発のやり方
デバイス依存のSDK等デバイス依存のSDK等機能の対応付け
プラグイン実装

Android開発環境

API仕様

Swaggerツール
プラグイン実装
自動生成

実装への落とし込み作業
デバイスコネクト
プラグイン環境

現在
API仕様から各環境のコードを生成

API
仕様

デバイスコネクト
プラグイン環境

Android用
ソースコードiOS開発環境

自動生成

自動生成

API
ドキュメント

自動生成

iOS用
ソースコードNode.js用
ソースコード機能の対応付け
デバイス依存のSDK等

Copyright© 2017 NTT DOCOMO, Inc. All rights reserved

14以前のデバイスＷｅｂＡＰＩの構造

各種アプリ

デバイスWebＡＰＩ

本体（仮想サーバ）

画面

デバイスWebＡＰＩ
マネージャ

プラグインSDK

プラグインSDK
加速度

ﾌﾟﾗｸﾞｲﾝ探索
セキュリティ

通知

加速度

画面

通知
ソナー

デバイス1用プラグイン
加速度

デバイス2用プラグイン

通知(画面＋振動の組合せ）
画面振動

加速度画面通知ソナー

デバイス1用ライブラリ

デバイス2用ライブラリ

デバイス１

デバイス２

Copyright© 2017 NTT DOCOMO, Inc. All rights reserved

デバイスWebＡＰＩ
プラグイン

ソナー

15

現在のデバイスＷｅｂＡＰＩの構造
各種アプリ

デバイスWebＡＰＩﾌﾟﾗｸﾞｲﾝ探索
セキュリティ
プラグインからAPI設計を取得できるように拡張本体（仮想サーバ）

プラグインSDK

プラグインSDK
加速度

画面
通知
API設計情報

加速度

デバイス1用プラグイン
加速度

デバイスWebＡＰＩ
マネージャ

画面
通知
API設計情報

ソナー
デバイスWebＡＰＩ
プラグイン

デバイス2用プラグイン

通知(画面＋振動の組合せ）
画面
振動

加速度

画面

通知

ソナー

デバイス1用ライブラリ

デバイス2用ライブラリ

デバイス１

デバイス２

Copyright© 2017 NTT DOCOMO, Inc. All rights reserved

ソナー

16

Swaggerでのスケルトンコード生成

・DeviceConnect-SpecレポジトリにAPI仕様をSwagger 2.0形式で取りまとめて公開
https://github.com/DeviceConnect/DeviceConnect-Spec

こちらのAPI記述を元にして、API設計の議論をしていきたい

Copyright© 2017 NTT DOCOMO, Inc. All rights reserved

17

Swaggerでのスケルトンコード生成

リファレンス

API仕様を書いた
JSONファイル

DeviceConnect
CodegenAndroid用
スケルトンコードビルド

プラグインAPK

Copyright© 2017 NTT DOCOMO, Inc. All rights reserved

18Symphonyの構造

Symphonyクラウド
API設計とダッシュボードからの設定により、クラウド上のAPIが動的に生成される

API設計
API設計
API設計

Webサービス画面
ダッシュボード
・機能アクセス権・ユーザ管理利用者A向けAPI・ライトの電源、色・テレビのチャンネル

API
利用者B向けAPI・ライト電源、色・テレビ電源、チャンネル・カギの開閉

各プラットフォームのSymphony
エージェント＋デバイスWebAPI

Android端末

API

Symphony
エージェントデバイスWebAPI
マネージャー

iOS端末

IoTゲートウェイ（Android）

Linux端末（node.js）

クラウド環境（node.js）

API

デバイスWebAPI
プラグイン
API設計

カギの仕様

Windows端末（node.js）

ライト、テレビ、エアコンの仕様
Copyright© 2017 NTT DOCOMO, Inc. All rights reserved

IoTゲートウェイ（node.js）
API設計
19

2年前に作った資料

DeviceConnectの目指すところ
クラウド

Bigdata処理クラウド

５Gネットワークサービス基盤

協創(+d)の実現
様々な解析・認識機能のオープン提供

さらなる次世代への発展

ｴｯｼﾞｺﾝﾋﾟｭｰﾃｨﾝｸﾞ

デバイスコネクトのクラウド化

機能の参照元・参照先をローカルからクラウドにするだけ

スマートフォン

様々なIoT規格
様々なIoT規格
様々なIoT規格

ローカル

様々なデバイス
様々なデバイス
様々なデバイス

デバイスコネクトの狙い

今あるデバイスは世の中の他のIoT規格化では対象外

サービスマルチレイヤーでのプロトコルにより、将来的にサービスとデバイスをおさえることを目指している

プロトコル

現状

デバイスコネクト⇒ローカルデバイスのWeb化

クラウドからローカルに近づく面も将来取り込めるものは何でも取り込む

ローカルとクラウドの間のWebインターフェースのみをｽﾏｰﾄﾌｫﾝを軸にしておさえた
うえで、クラウドへの発展を目指すIoTデバイス
一般的なIoT規格の狙い

20

ドキュメント整備・デザインパターン：用途・目的に応じたAPIの設計指針
・API作成ガイドライン：API記述の共通ルール

Copyright© 2017 NTT DOCOMO, Inc. All rights reserved

21

デバイスＷｅｂＡＰＩのデザインパターン

・One shot data ： HTTP GET/POSTでの単純アクセス
例： アクセスした瞬間の加速度センサーの値を取得（繰り返し値が欲しい場合はポーリング）
・Event driven data ： PUT/DELETE、WebSocketでのイベント処理
例： 加速度センサーの値に変化があった瞬間の値を連続的に自動取得※ただし、あくまでイベントとしての処理であり、大容量データは対象としない

・Streaming data ： URIの直接参照
例： 大容量の加速度センサーログの取得、低遅延・高サンプリングレートでのリアルタイムの加速度センサー値の取得等
シンプルで手軽なHTTPアクセスと、効率的なWebSocketによるイベント処理を両立
Copyright© 2017 NTT DOCOMO, Inc. All rights reserved

22

API作成ガイドライン
・APIの階層構造/gotapi/profile[/interface][/attribute]

・命名規則
例: PUT /gotapi/mediaPlayer/play※lowerCamelCase

誤: PUT /gotapi/meida_payer/play
PUT /gotapi/meida-payer/play
PUT /gotapi/MeidaPayer/Play
PUT /gotapi/meidapayer/play※snake_case※UpperCamelCase※ただし、大文字・小文字の違いについては互換性のために内部的には許容している・レスポンス定義、エラーコード等、API記述の共通ルールを整備

https://github.com/DeviceConnect/DeviceConnect-Docs/wiki/Specification-Api-Guidelines

Copyright© 2017 NTT DOCOMO, Inc. All rights reserved

23

意見交換の場について

https://github.com/DeviceConnectUsers/Community/

GitHubのDeviceConnectはドコモで立ち上げたプロジェクトDeviceConnectUsersはドコモ管理外のGithub.ioでのコミュニティサイト（立ち上げ：MOONGIFTさん）

Copyright© 2017 NTT DOCOMO, Inc. All rights reserved

24