Specification Api Guidelines - TakayukiHoshi1984/DeviceConnect-Docs GitHub Wiki
API作成ガイドライン
ここでは、Device Connect API を作成するためのガイドラインを解説します。
Device Connect API とは
各サービスの機能にアクセスするために Device Connect システムで定義したAPIです。
Device Connect API は、プロファイル単位で Swagger 2.0 で規定されるフォーマットで記述します。 各プロファイルの定義は、DeviceConnect-Spec を参照してください。
また、アプリケーションは、ServiceInformation APIで、その定義を取得することができ、サービスがサポートしているAPIを確認することができます。
リクエストの定義
リクエストは、RESTの仕様であるArchitectural Styles and the Design of Network-based Software Architectures CHAPTER 5 Representational State Transfer (REST)を参考にして、Device Connect APIを定義します。
共通パラメータ
アプリケーションはリクエストを送信する際、下記のパラメータが必要になります。
| 論理名 | 物理名 | データ型 | 省略 | 設定値 |
|---|---|---|---|---|
| アクセストークン | accessToken | string | 右記参照 | Authorization APIで取得したアクセストークン。Availability API、Authorization APIのみ省略可。それ以外のAPIでは必須。GotAPIの仕様のため、詳細はこちらを参照してください。 |
| ワンタイムトークン | nonce | string | ○ | HMAC生成用のワンタイムトークン。GotAPIの仕様のため、詳細はこちらを参照してください。 |
なお、 Device Connect Managerでは、設定画面において、アプリケーション認可機能の有効/無効を切り替えることができます。
アプリケーション認可機能が無効に設定されている場合には、accessTokenを省略することができます。
HTTPメソッド一覧
Device Connect APIでは以下のHTTPメソッドをサポートしています。
| HTTPメソッド |
|---|
| GET |
| PUT |
| POST |
| DELETE |
HTTP アクセス制御 (CORS)に対応するために、OPTIONSヘッダについては、Webサーバ側でレスポンスを返却します。
Access-Control-Allow-Origin: *
Device Connect Managerは、CORSのレスポンスで全てのOriginに対して許可を行います。
リクエストURIの規則
Device Connect では、以下の規則に基づいて、Device Connect APIを定義します。 以下の定義に従い、Swagger 2.0のフォーマットで定義ファイルを記述します。
1. セグメント階層
URIは、/api/profile/interface/attributeのセグメントで定義します。
- interfaceとattributeは省略可能である。
- interfaceが存在する時は、attributeは省略不可とする。
例) interfaceとattributeが省略された場合
/api/profile
例) interfaceが省略された場合
/api/profile/attribute
例) 省略がない場合
/api/profile/interface/attribute
1.1. セグメントの説明
| セグメント | 省略 | 説明 |
|---|---|---|
| api | - | Device Connect APIが使用するAPIの名前を指します。 OMAのGotAPIを元にしているため、apiは「gotapi」を指定しています。 |
| profile | - | ユニークな機能ごとにそれぞれprofileを割り当てます。 |
| interface | ○ | 提供されるプロファイルで、細分化できる機能がある場合にはinterfaceとして割り当てます。 |
| attribute | ○ | 提供されるプロファイルで、取得・操作が可能な属性を持つ場合にattributeとして割り当てます。 |
1.2. セグメント構成の例外
Device Connectでは、GETメソッドを用いて、POST/PUT/DELETEを操作できるようにするために、以下のようなセグメントを定義します。
/api/method/profile/interface/attribute
| セグメント | 省略 | 説明 |
|---|---|---|
| method | ○ | PUT、POST、DELETEの代替操作を行うためのメソッドを指定します。 |
例) GETメソッドで、PUT操作相当を行う
GET /gotapi/put/mediaPlayer/play
GET以外のHTTPメソッドを使用している場合には、methodを指定することはできません。
2. URIの命名規則
api、profile、interface、attributeの各セグメントは、以下の命名規則に基づき定義します。
- ローワーキャメルケースで定義する。
- セグメントは複数単語(2,3単語程度)に収める。
- 意味のない冗長な単語はなるべく使用しない。
- UnixやDOSなどのコマンド名を使用しない。
例) ローワーキャメルケースで定義する。
正: PUT /gotapi/mediaPlayer/play
誤: PUT /gotapi/meida_payer/play
PUT /gotapi/meida-payer/play
ただし、Device Connectシステムでは、profile、interface、attributeの大文字小文字を無視して処理を行います。
3. 一般的な略語
一般的な略語は使用して良いこととします。
例) 一般的な略語
PUT /gotapi/tv
PUT /gotapi/ecg/onECG
一般的でない略語や複数の意味を持つような単語を使用する場合には、その旨をWikiなどで説明します。
例) 一般的でない略語
PUT /gotapi/omnidirectionalImage/roi
ROIは、「Region Of Image」の意味で使用していますが、「Return On Investment」などの略語の可能性もあるため、説明を追加する必要があります。
4. 数値
値の範囲が決まっているのならば、/profile/interface/attributeに数値などを含めても良いこととします。
- 可変的に数値を変えられるような数値は使用しない。
- 推奨としては、0〜10程度の範囲とする。
例) GPIOのピン番号
GET /gotapi/gpio/export/pin0
GET /gotapi/gpio/export/pin1
GET /gotapi/gpio/export/pin2
5. 同じ綴り
同じ綴りのAPIは用意しないようにします。
例) onECGとoneCgで同じ綴り
PUT /gotapi/ecg/onECG
PUT /gotapi/ecg/oneCg
6. 商品名等
造語、商品名などは、汎用性のない操作を定義する時に使用します。
例) Spheroのデバイスの機能を使用する
PUT /gotapi/sphero/quaternion/onQuaternion
Spheroは、アメリカ Spheroのアメリカおよびその他の国における登録商標または商標です。
7. 動詞
RESTでは動詞を使用してはいけないが、Device Connect APIでは分かりやすさを重視して使用しても良いこととします。
- profileは名詞にする。
- interface、attributeは動詞を使用しても良い。
例) attributeに動詞を使用
POST /gotapi/notification/notify
POST /gotapi/phone/call
8. 予約語
既存のGotAPIやDevice Connect APIで定義されているProfileは、予約語となるために独自Profileで使用することはできません。
例) 既に定義されているプロファイル
GET /gotpai/availibity
GET /gotpai/files
など
9. イベント
イベント処理の設定を行うAPIは、attributeにonというプレフィックスを付けます。
例) イベントの登録
PUT /gotapi/battery/onChargingChange
PUT /gotapi/deviceOrientation/onDeviceOrientation
例) イベントの解除
DELETE /gotapi/battery/onChargingChange
DELETE /gotapi/deviceOrientation/onDeviceOrientation
9.1. イベントの例外
GotAPIで定義されているイベント処理では、onが付かない場合があります。
例) GotAPIで定義されているAPI
PUT /gotapi/health/heart
レスポンス定義
Device Connect APIへのリクエストに対するレスポンスは、以下の値を返します。
- ステータスコードは、200で返します。
- HTTPレスポンスヘッダのContent Typeには、application/jsonを返します。
- HTTPレスポンスボディには、JSONを返します。
ただし、リソースにアクセスを行うfilesプロファイルなどへのリクエストに対しては、バイナリを返却します。
共通パラメータ
Device Connect Managerからのレスポンスには以下のパラメータが返却される。
| 論理名 | 物理名 | データ型 | 省略 | 備考 |
|---|---|---|---|---|
| 処理結果 | result | 数値 | - | 0:正常応答0以外:異常応答 |
| プロダクト名 | product | 文字列 | - | 処理を行った Device Connect Managerの名前 |
| バージョン名 | version | 文字列 | - | 処理を行った Device Connect Managerのバージョン名 |
| HMAC | hmac | 文字列 | ○ | Device Connect Managerの正当性を示すための署名。アプリケーションが事前にHMAC生成鍵を送信していなかった場合は省略されます。 |
レスポンス例
{
"product" : "Device Connect Manager",
"version" : "2.0.0",
"result" : 0,
"playStatus" : {
"mediaId" : "media001",
"mimeType" : "audio/mp3",
"status" : "play",
"trackNo" : 5,
"pos" : 80
},
"hmac" : "abcdef0123456789"
}
エラーレスポンス
リクエストに対するレスポンスは result が 0以外 のとき、以下の項目を含むレスポンスを返却します。
エラーレスポンスの共通パラメータ
| 論理名 | 物理名 | データ型 | 備考 |
|---|---|---|---|
| エラーコード | errorCode | 数値 | エラーを識別するためのコード |
| エラーメッセージ | errorMessage | 文字列 | エラーの内容 |
エラーレスポンス例
{
"product" : "Device Connect Manager",
"version" : "2.0.0",
"result" : 1,
"errorCode" : 1,
"errorMessage" : "Unknown error."
}
エラーコード一覧
| エラーコード | エラー内容 |
|---|---|
| 1 | 原因不明のエラー |
| 2 | 未サポートプロファイルエラー |
| 3 | 未サポートアクション(HTTPメソッド)エラー |
| 4 | 未サポートアトリビュートエラー |
| 5 | デバイスID未設定エラー |
| 6 | デバイス発見失敗エラー |
| 7 | タイムアウトエラー |
| 8 | 未知のインターフェースへのアクセスエラー |
| 9 | バッテリー低下による操作不能エラー |
| 10 | 不正なリクエストパラメータエラー |
| 11 | 認証エラー |
| 12 | アクセストークン有効期限切れエラー |
| 13 | アクセストークン未設定エラー |
| 14 | スコープ外へのアクセスエラー |
| 15 | 認証時にクライアントIDを発見できなかったエラー |
| 16 | デバイス状態異常エラー |
| 17 | サーバー状態異常エラー |
| 18 | リクエストの発行元が不正 |
| 19 | リクエストURLが不正 |
| 20 | Profile名が不正 |
| 21 | リクエスト先のプラグインが無効 |
| 22 | リクエスト先のプラグインの異常発生により連携停止中 |