Skip to content

Specification GotAPI

Jump to bottom
TakayukiHoshi1984 edited this page Sep 11, 2017 · 2 revisions

GotAPI

標準化団体 OMA (Open Mobile Alliance) にて Generic Open Terminal API Frameworkとして標準化された各サービス(デバイス)を操作するためのAPI仕様になります。

詳しくは、GotAPIの資料を参照してください。

GotAPI Interface

GotAPI Interface は、標準化したAPIを定義し、各サービスの発見、操作などを行う機能を提供します。

Device Connectシステムでは、GotAPI Interface が定義している以下のAPIを実装しています。

  • Availability API
  • Authorization API
  • ServiceDiscovery API
  • ServiceInformation API

Availability API

GotAPI Serverが使用可能状態にあるかの確認を行う機能を提供します。

リクエスト
GET /gotapi/availability HTTP/1.1
Host: localhost:4035
Origin: http://app.example.com
レスポンス
{
    "result":0
}

Authorization API

GotAPI Auth Serverにユーザ認可を求める機能を提供します。
ユーザに認可された場合にアクセストークンを取得することができます。

Availability、Authorization 以外のAPIにアクセスする場合には、このAPIで取得したアクセストークンを一緒に送らないとアクセスすることができません。

Grant

クライアントIDを生成する機能を提供します。

リクエスト
GET /gotapi/authorization/grant HTTP/1.1
Host: localhost:4035
Origin: http://app.example.com
レスポンス
{
    "result":0,
    "clientId": "0123456789",
    "errorCode": 0,
    "errorMessage": "" ,
    "hmac": "0123.....xyz"
}

AccessToken

Grantで生成したクライアントIDを元に、アクセストークンを生成する機能を提供します。
このAPIが呼び出された時点でユーザに認可を求めます。
ユーザ認可された場合には、アクセストークンを生成し返却します。
また、ユーザ認可されなかった場合にはアクセストークンを生成せずに、エラーを返却します。

リクエスト
GET /gotapi/authorization/accesstoken?clientId=0123456789&scope=notification,vibration&applicationName=Smart%20Watch&20Controller HTTP/1.1
Host: localhost:4035
Origin: http://app.example.com
レスポンス
{
    "result": 0,
    "accessToken": "9876543210",
    "errorCode": 0,
    "errorMessage": "" ,
    "hmac": "0123.....xyz"
}

このAPIが呼び出された時点で、Device Connect Managerは、ユーザに使用の認可を求めるダイアログを表示します。
また、一定時間ユーザから認可を得られなかった場合もエラーを返却します。

ServiceDiscovery API

GotAPI Serverに接続されているサービス(デバイス)一覧を取得する機能を提供します。

例) ServiceDiscoveryでサービスを検索します。

リクエスト
GET /gotapi/servicediscovery?accessToken=xxxxx HTTP/1.1
Host: localhost:4035
Origin: www.example.com
レスポンス
{
    "product":"Device Connect Manager",
    "version":"x.x",
    "result":0,
    "services":[
        {
            "id":"device1.localhost.deviceconnect.org",
            "name":"Service1",
            "type":"Bluetooth",
            "online":true,
            "config":""
        },
        {
            "id":"device2.localhost.deviceconnect.org",
            "name":"Service2",
            "type":"WiFi",
            "online":false,
            "config":""
        }
    ]
}

ServiceInformation API

GotAPI Serverからサービス(デバイス)の詳細な情報を取得する機能を提供します。

例) ServiceDiscoveryで発見したサービスのidを指定して詳細な情報を取得します。

リクエスト
GET /gotapi/serviceinformation?accessToken=xxxxx&serviceId=device1.localhost.deviceconnect.org HTTP/1.1
Host: localhost:4035
Origin: www.example.com
レスポンス
{
    "product":"Device Connect Manager",
    "version":"x.x",
    "result":0,
    "connect":{
        "wifi":true
    },
    "supports":[
        "system",
        "battery",
        "vibration"
    ],
    "supportApis": [
        "battery" : {
            // ...省略...
        },
        "vibration" : {
            // ...省略...
        }
    ]
}

Device Connect Managerでは、拡張機能として、supportApisにSwagger2.0で定義されたAPIの情報を格納します。

GotAPI セキュリティ

GotAPIでは、以下のようなセキュリティを定義しています。

リクエストの発行元を明示

OMA GotAPI v1.1 の規定に従い、アプリケーションは、リクエストにOriginヘッダを付加する必要があります。
GotAPIのセキュリティ機能であるアプリケーション認可機能やホワイトリスト機能は、Originヘッダの情報を元に処理されます。

また、HTMLアプリケーションとNativeアプリケーションでは、付加するヘッダが異なります。

  • HTMLアプリケーションの場合

RFC6454上で定義されるOriginをOriginヘッダに指定します。

GET /gotapi/availability HTTP/1.1
Host: 127.0.0.1:4035
Origin: http://xxx.example.com/

ブラウザ上で動作させると思いますので、自動的に付加されるので、開発者はあまり気にする必要はありません。

  • Nativeアプリケーションの場合

X-GotAPI-OriginヘッダにNativeアプリケーションの識別子(Androidの場合はパッケージ名等)を指定します。

GET /gotapi/availability HTTP/1.1
Host: 127.0.0.1:4035
X-GotAPI-Origin: com.example.android.app

なお、Device Connect Managerでは、両方のヘッダが指定された場合は、Originヘッダを優先して使用します。

本機能はDevice Connect Managerの設定画面で有効/無効を切り替えることができます。
本機能を無効にした場合は、Originが不要になるためにアプリケーション認可機能やホワイトリスト機能も同時に無効になります。

アプリケーション認可機能

ユーザが認可していないアプリケーションからのアクセスをブロックする機能です。

アプリケーションは、初めてGotAPI Serverにアクセスする際、ユーザからの認可とともに、アクセストークンを取得する必要があります。
アクセストークンは、Authorization APIで取得します。

アクセストークン無しでデバイスにアクセスしようとした場合、GotAPI Serverはアプリケーションに対してエラーを返却します。

WebSocketをGotAPI Serverに接続しようとした場合にも、同様にアクセストークンが必要になります。

アクセストークン無しでWebSoketを接続しようとした場合に、GotAPI Serverは{"result":1}を通知してWebSocketを切断します。

なお、本機能はDevice Connect Managerの設定画面で有効/無効を切り替えることができます。
無効にされた場合には、アクセストークンの有無は無視します。

ホワイトリスト機能

ホワイトリストに含まれないアプリケーションからのアクセスを禁止する機能です。
また、ユーザに対してアプリケーションのホワイトリスト管理機能及びUIと本機能の有効/無効を操作するUIを提供します。
これによりユーザ操作によって切り替え可能にします。

本機能が有効になっている場合、アプリケーションから受信したリクエストメッセージのOriginヘッダをチェックし、Originがホワイトリストに含まれていない場合、エラーを返却します。

HMACサーバ検証機能

アプリケーション側でGotAPI Serverの正当性を検証する機能を提供します。

アプリケーション側で、GotAPI Serverの正当性を検証できるように、アプリケーションからのリクエストへの応答にHMACを付加します。
本機能の使用・不使用はアプリケーション側に委ねられています。

HMACを生成するためのキーをGotAPI Serverに送信するためにURLスキームを使用します。
以下のようにURLスキームのパラメータにキーを含めることで送信します。

  • 例) Android(Chrome)
<a href="intent://#Intent;scheme=gotapi;package=com.example.gotapi;S.origin=app.example.jp;S.key=0123456789;;end">Invoke the GotAPI Server</a>

GotAPI Serverでは、受け取ったキーを保持し、アプリケーションからのリクエストに付加されているnonceからHMACを計算してレスポンスに返却します。
アプリケーションでは、キーとnonceからHMACを生成して、GotAPI Serverから返却されたHMACと比較して正当性を確認します。

ただし、アプリケーションがnonceをリクエストに付加していない場合には、HMACの処理は行われません。

Clone this wiki locally