はじめに

Nature Remo Cloud API(以降API) を利用することで、Nature Remo(以降Remo)のセンサから得られる情報を取得する、Remoから赤外線を送信する、などのアクションを行うことができる。


APIは、HTTPクライアントがNatureのサーバへHTTPSリクエストを行うことで利用する。レスポンスはJSON形式である。

Nature Remo クラウドがインターネットに向けて提供するAPIの詳細は API仕様 [Cloud API] を、Nature Remoデバイスがローカルネットワークに提供するローカルのAPIの詳細は API仕様 [Local API] を参照。

 

OAuth2

認証、認可にはOAuth2を利用する。
APIを利用する際には、必ず以下のHTTPヘッダを付加する。

Authorization: Bearer {TOKEN}

{TOKEN} 部には、OAuth2を通して取得したアクセストークンを入れる。

自分のアクセストークンは、home.nature.globalより新規発行や失効することができる。

 

エラー

APIを利用したアクションの結果は、HTTPステータスコードで表す。 HTTPステータスコードの意味については、RFC7231を参照。

 

バージョニング

APIを利用してアクションを行う際には、 GET または POST リクエストを、APIドキュメント swagger.nature.global に記載の path に対して発行する。


path 内の {VERSION} はアクション毎に更新する。 {VERSION} が変わらなければ、その特定のアクションに対して、ドキュメントに記載されているパラメータの範囲内で、必須リクエストパラメータの追加及び既存のレスポンスパラメータの削除、仕様変更は行わない。


必須リクエストパラメータの追加、レスポンスパラメータの削除、仕様変更が必要な際には、新しい {VERSION} 番号を決定しその {VERSION} を含む path へのリクエストには新しい仕様にしたがってアクションを行う。Nature, Inc.からの告知の後、一定期間
を経て古い {VERSION} に対するリクエストはステータスコード 404 を返す。

 

リクエスト制限

サーバは 5分以内に30回 以上のリクエストを受けるとその後ステータスコード 429 を返す。

以下のHTTPリクエストのレスポンスヘッダで最新の制限状態を確認できる。

  • X-Rate-Limit-Limit
  • X-Rate-Limit-Reset
  • X-Rate-Limit-Remaining