デバイス WebAPI設計の進め方

Copyright© 2017 NTT DOCOMO, Inc. All rights reserved 1
デバイスWebAPI設計の進め方
2017/7/14
株式会社ＮＴＴドコモ

Copyright© 2017 NTT DOCOMO, Inc. All rights reserved
デバイスWebAPI技術のおさらい
2

メガネ型
デバイス
ひとつひとつのデバイスや規格にあわせ、それぞれの環境での開発が必要
温度
センサー
Android
時計型
デバイス
アクション
カメラ
スマートトイ
（おもちゃ）
iPhone
Windows
様々な実行環境、開発環
境
様々な
通信プロトコル
様々なデバイス
ネイティブ
アプリ
Webアプリ／
Webブラウザ
ハイブリッド
アプリ
無線LAN
Bluetooth
USB
…
…
…
デバイス毎のSDK,API、仕様等
スマート
家電A規格
心拍数計
体重計
スマート
家電B規格
Android用
A規格SDK
iOS用
B規格API
Android用
Cデバイス向け
管理アプリ
D規格用
接続仕様
iOS用
A規格SDK
BLE
Android
アプリ開発者
Webアプリ
開発者
iOSアプリ
開発者
…
E用クラウド
データ取得API
スクリプト言語
開発者
…
デバイスを
使いたい開発者
開発
スマートフォンにつながる様々なデバイスの現状
3

Android
アプリ開発者
Webアプリ
開発者
iOSアプリ
開発者
開発者
デバイスを
メガネ型
デバイス
温度
センサー
Android
時計型
デバイス
アクション
カメラ
スマートトイ
（おもちゃ）
iPhone
Windows
境
様々な
ネイティブ
アプリ
Webアプリ／
Webブラウザ
ハイブリッド
アプリ
無線LAN
Bluetooth
USB
…
…
…
スマート
家電A規格
心拍数計
体重計
スマート
家電B規格
Android用
A規格SDK
iOS用
B規格API
Android用
Cデバイス向け
管理アプリ
D規格用
接続仕様
iOS用
A規格SDK
BLE
…
E用クラウド
データ取得API
色々な仕様を
覚えるのが大変
環境にあわせた
作りこみが必要
通信の仕組みの
違いにあわせた
開発が必要
開発環境の
構築が大変
デバイスアクセス
が制限された環境
…
そもそも
作れない
ひとつひとつのデバイスや規格にあわせ、それぞれの環境での開発が必要
スマートフォンにつながる様々なデバイスの現状
4

メガネ型
デバイス
デバイスの持つ機能に、共通の記述（ＷｅｂＡＰＩ）でアクセスする仕組みで
現状の課題を解決
温度
センサー
Android
時計型
デバイス
アクション
カメラ
スマートト
イ
（おも
ちゃ）
iPhone
Windows
境
ネイティブ
アプリ
無線LAN
Bluetooth
USB
…
…
…スマート
家電A規
格
心拍数計
体重計
スマート
家電B規
格
Android用
A規格SDK
iOS用
B規格API
Android用
Cデバイス向け
管理アプリ
D規格用
接続仕様
iOS用
A規格SDK
BLE
…
E用クラウド
データ取得API
…
…
Web
インター
フェース
Webアプリ／
Webブラウザ
ハイブリッド
アプリ
共通の記述
（WebAPI）
Android
アプリ開発者
Webアプリ
開発者
iOSアプリ
開発者
開発者
デバイスを
違いを意識する
必要がなくなる
仕組みの違いを
意識する必要なし
様々な
機能
デバイス１
デバイス２
デバイス３
ライト
画面加速度
心拍数
カメラ
通知
画面
加速度通知
スマートフォン
経由での、他の
環境からの利用
デバイスを機能
の集合として表現
どの開発者も
共通の記述を
覚えるだけ
デバイスＷｅｂＡＰＩとは？
5

参考：そもそもＷｅｂＡＰＩとは？
6
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等）に書くか）

フレームワーク
ライブラリ
Kernel
デバイス
Android OS
仮想サーバ
IPネットワーク層
Webブラウザ
Webアプリ
(HTML5+Javascript)
Webアプリ
(HTML5+Javascript)
Webアプリ
(HTML5+Javascript)
拡張プラグインC
拡張プラグインB
拡張プラグインA
デバイスアクセス要求を
各デバイスの制御命令に
変換（プラグインで拡張）
ネイティブアプリ
として任意の機能
が利用可能
IPネットワーク経由で
仮想サーバにアクセス
デバイスWebAPI
インターネット上のWebサイト
スマートフォン上で動作する仮想サーバに、スマートフォン内部のIPネットワーク
層を経由することで、Webブラウザからでも高度な機能アクセスを実現
ネイティブアプリからも同様に利用可能
どうやって実現しているか
7

デバイスWebAPI
（機能単位のREST API規定）
デバイスWebAPI
Webアプリ(HTML5+Javascript)
Webブラウザ
Webエンジン
デバイス
低レイヤー
デバイスAPI規定
（JavaScript）
ドライバ/Profile相当
（JavaScript）
ドライバ/Profile
最近のWeb規格化の流れ
(Extensible Web)
低レイヤーの
ドライバ
Web
アプリ
Web
ブラウザ
スクリプト
エンジン
Python・
Ruby等
ネイティブ
アプリ
仮想サーバ＋REST API I/F
（GotAPIでの規定部分）
デバイスWebAPI
低レイヤーの
ドライバ
ドライバ/
Profile
デバイス
ある意味でｴﾝﾀｰﾌﾟﾗｲｽﾞ開発
における最近のｱｰｷﾃｸﾁｬｽﾀｲﾙ
(Micro Services)に近い？
一般的なWebアプリ（Webブラウザ）
からのデバイス利用、トレンド
デバイスWebAPIでのデバイス利用
ドライバ/Profile相当ドライバ/Profile相当
ドライバ/Profileドライバ/Profile
Webのトレンドで見た場合※2年前の資料

Webブラウザ
Webエンジン
デバイス
低レイヤー
（JavaScript）
（JavaScript）
低レイヤーの
ドライバ
一般的なWebアプリ（Webブラウザ）からのデバイス利用
ブラウザでのデバイスAPIの現状
カメラ、マイク等
の一部機能への
対応が若干進む
Chromeブラウザが
WebBluetoothを
正式サポート開始
Webブラウザも限定的にデバイス機能アクセスの範囲が拡大中だが
前述の課題は残ったまま

Webのトレンドから見てデバイスＷｅｂＡＰＩはどうなったか？
デバイスWebAPI
デバイスWebAPI
Webブラウザ
Webエンジン
デバイス
低レイヤー
（JavaScript）
（JavaScript）
最近のWeb規格化の流れ
(Extensible Web)
低レイヤーの
ドライバ
Web
アプリ
Web
ブラウザ
スクリプト
エンジン
Python・
Ruby等
ネイティブ
アプリ
仮想サーバ＋REST API I/F
（GotAPIでの規定部分）
デバイスWebAPI
低レイヤーの
ドライバ
ドライバ/
Profile
デバイス
一般的なWebアプリ（Webブラウザ）
からのデバイス利用、トレンド
デバイスWebAPIでのデバイス利用
ある意味でｴﾝﾀｰﾌﾟﾗｲｽﾞ開発
における最近のｱｰｷﾃｸﾁｬｽﾀｲﾙ
(Micro Services)に近い？

ＷｅｂＡＰＩのトレンド
11
・サーバレスアーキテクチャ
自前サーバではなく、AWS(Amazon Web Serivce)等のクラウド基盤
を活用したサービス設計
・マイクロサービス
一枚板なサービス基盤を作るのではなく、OSといった実行環境や
開発環境の違う小さなサービスを組み合わせて一つのサービスを
提供する設計。サービス間の環境の違いを吸収してつなげるため
に、WebAPIが用いられる。
・ＷｅｂＡＰＩ設計の国際標準化
AWSのAPI Gateway等で使われているAPI記述仕様のSwaggerをベー
スとした標準化が、ﾏｲｸﾛｿﾌﾄ,Google等が立ち上げたOpen API
Initiativeで進行中。
WebAPIのトレンド（API記述の標準化）を
デバイスWebAPIでも活用

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

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

デバイスWebAPIでもSwaggerベースでのモデルファーストの
フレームワーク提供
⇒同一のAPI設計で、様々な環境での機能提供を実現
Android開発環境
デバイスコネクト
プラグイン環境
プラグイン実装
デバイス依存
のSDK等
API
仕様
iOS開発環境
プラグイン環境
プラグイン実装
デバイス依存
のSDK等
現在
API仕様から各環境のコードを生成
以前
一般的なアプリ開発のやり方
機能の対応付け
実装への落とし込み作業
API仕様
Swaggerツール
API
ドキュメント
Android用
ソースコード
iOS用
ソースコード
Node.js用
ソースコード
デバイス依存のSDK等
機能の対応付け
自動生成
自動
生成
自動生成自動生成
Ｓｗａｇｇｅｒベースでのモデルファースト開発

以前のデバイスＷｅｂＡＰＩの構造
15
本体（仮想サーバ）
デバイス1用プラグイン
各種アプリ
デバイス1用ライブラリ
デバイス１
加速度画面
加速度画面通知
デバイス２
加速度画面通知ソナー
ソナー
ソナー
通知(画面＋振動の組合せ）
ﾌﾟﾗｸﾞｲﾝ探索
セキュリティ
プラグインSDK プラグインSDK
振動
デバイスWebＡＰＩ
マネージャ
プラグイン

現在のデバイスＷｅｂＡＰＩの構造
16
本体（仮想サーバ）
各種アプリ
デバイス１
加速度画面
デバイス２
加速度画面通知ソナー
API設計情報
ソナー
通知(画面＋振動の組合せ）
ﾌﾟﾗｸﾞｲﾝ探索
セキュリティ
プラグインSDK プラグインSDK
振動
マネージャ
プラグイン
API設計情報
ソナー
プラグインからAPI設計を
取得できるように拡張

Swaggerでのスケルトンコード生成
・DeviceConnect-SpecレポジトリにAPI仕様を
Swagger 2.0形式で取りまとめて公開
https://github.com/DeviceConnect/DeviceConnect-Spec
こちらのAPI記述を元にして、
API設計の議論をしていきたい

Swaggerでのスケルトンコード生成
DeviceConnect
CodegenAPI仕様を書いた
JSONファイル
Android用
スケルトンコード
リファレンス
プラグインAPK
ビルド

デバイスWebAPI
マネージャー
デバイスWebAPI
プラグイン
API設計
Symphony
エージェント
Symphonyクラウド
API
API設計API設計API設計
Android端末
iOS端末
Linux端末
（node.js）
Windows端末
（node.js）
クラウド環境
（node.js）
IoTゲートウェイ
（node.js）
IoTゲートウェイ
（Android）
各プラットフォームのSymphony
エージェント＋デバイスWebAPI
利用者A向けAPI
・ライトの電源、色
・テレビのチャンネル
利用者B向けAPI
・ライト電源、色
・テレビ電源、チャンネル
・カギの開閉
ライト、テレビ、エアコンの仕様
ダッシュボード
・機能アクセス権
・ユーザ管理
Symphonyの構造
API設計とダッシュボードからの
設定により、クラウド上のAPIが
動的に生成される
API設計
カギの仕様
API
API
Webサービス画面

DeviceConnectの目指すところ
20
Bigdata処理クラウド
５Gネットワーク
様々な解析・認識機能のオープン提供
クラウド
ローカル
スマートフォン
ｴｯｼﾞｺﾝﾋﾟｭｰﾃｨﾝｸﾞ
デバイスコネクトのクラウド化
機能の参照元・参照先をローカルからクラウド
にするだけ
様々なデバイス様々なデバイス
IoTデバイス
協創(+d)の実現
将来
⇒ローカルデバイスのWeb化
現状
プ
ロ
ト
コ
ル
マルチレイヤーでの
プロトコルにより、
将来的にサービスと
デバイスをおさえる
ことを目指している
サービス
一般的なIoT規格の
狙い
ローカルとクラウドの間の
Webインターフェースのみを
ｽﾏｰﾄﾌｫﾝを軸にしておさえた
うえで、クラウドへの発展を
目指す
さらなる次世代
への発展
様々なIoT規格
デバイスコネクトの狙い
サービス基盤
様々なIoT規格様々なIoT規格
クラウドから
ローカルに
近づく面も
取り込めるものは
何でも取り込む
今あるデバイスは世の中の
他のIoT規格化では対象外
2年前に作った資料

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

・One shot data ： HTTP GET/POSTでの単純アクセス
例：アクセスした瞬間の加速度センサーの値を取得（繰り返し
値が欲しい場合はポーリング）
・Event driven data ： PUT/DELETE、WebSocketでのイベント処理
例：加速度センサーの値に変化があった瞬間の値を連続的に
自動取得
※ただし、あくまでイベントとしての処理であり、大容量データは対象としない
・Streaming data ： URIの直接参照
例：大容量の加速度センサーログの取得、
低遅延・高サンプリングレートでのリアルタイムの加速度
センサー値の取得等
シンプルで手軽なHTTPアクセスと、効率的なWebSocketによるイベント処理を両立
デバイスＷｅｂＡＰＩのデザインパターン
22

API作成ガイドライン
・APIの階層構造 /gotapi/profile[/interface][/attribute]
・命名規則
例: PUT /gotapi/mediaPlayer/play ※lowerCamelCase
誤: PUT /gotapi/meida_payer/play ※snake_case
PUT /gotapi/meida-payer/play
PUT /gotapi/MeidaPayer/Play ※UpperCamelCase
PUT /gotapi/meidapayer/play
※ただし、大文字・小文字の違いについては互換性のために内部的には許容している
・レスポンス定義、エラーコード
等、API記述の共通ルールを整備
https://github.com/DeviceConnect/DeviceConnect-Docs/wiki/Specification-Api-Guidelines

https://github.com/DeviceConnectUsers/Community/
意見交換の場について
GitHubのDeviceConnectはドコモで立ち上げたプロジェクト
DeviceConnectUsersはドコモ管理外のGithub.ioでのコミュニティサイト
（立ち上げ：MOONGIFTさん）

デバイス WebAPI設計の進め方

More Related Content

What's hot

Similar to デバイス WebAPI設計の進め方

More from Device WebAPI Consortium

デバイス WebAPI設計の進め方