Hatena::ブログ(Diary)

TAKUYA’s CODE RECORDER このページをアンテナに追加 RSSフィード

2009-06-23

AMEE API / API Operations

|

AMEEのAPIページを読み進めていますが、いろいろと勉強しなければならない部分を見つけました。まずは、RESTfulなAPIの使い方について、その背景なんかも交えながら学んでいこうと思います。

http://my.amee.com/developers/wiki/ApiOperations

  • Overview
    • AMEEのリソース
      • AMEE API経由で利用可能
      • 親切なRESTianスタイルなURLsを使える
      • 標準的なHTTPメソッド(GET/POST/PUT/DELETE)で操作する
    • リソースのid
      • AMEEの多くのリソースはunique ID(UID)によって分類(identified)される
      • これらのUIDは、APIのレスポンスとともに返ってくる
      • 他のAPI操作において使うこともできる
  • Fetching resources (GET method)
    • 全てのリソースはHTTPのGETメソッドを使ってフェッチされる
      • RESTian規約に従って、リソースは階層的なURL構造になっている
    • GETメソッドだけでは、リソースを操作することはできない
      • 他のHTTPメソッドが、リソースの生成・編集・削除のために使われる
    • 階層情報をフェッチする方法
      • URL階層のより深いリソースをフェッチしなければならない時もある
      • 全てのリソースは、上位階層・下位階層へ移動するために必要な情報を持っている
    • 例えば
      • DataCategoryリソースは、他のDataCategoriesやDataItemsから構成されている
      • DataCategoryをフェッチした後、レスポンス情報を使って、下位のリソースへナビゲートすることが可能になる
    • URLのアーキテクチャ
  • Creating new resources (POST method)
    • リソースは、HTTPのPOSTメソッドを使って生成される
    • ほとんどのリソースは、親のリソースにPOSTingすることによってのみ生成される
      • 例えば、新しいProfileItemを追加したい場合、親となるProfileCategoryにポストする必要がある
    • POSTメソッドをサポートしているリソースは、受入可能なパラメータの定義セットを持っている
      • 例えば、nameやvalue
      • 新しいリソースをPOSTingした後は、このwikiで書かれている通り、URL規約にしたがって、新しいURLが利用可能となる
    • POSTすると、関連するHTTPのステータスコードが返ってくる
      • 制限のある(limited)XMLやJSONを返すこともある
  • Modifying resources (PUT method)
    • リソースは、HTTPのPUTメソッドで修正することができる
      • 全てのリソースが変更できるわけではない
      • 権限がある場合のみ修正することができる
    • リソースは、ユニークなURLを使えば、PUTによって直接修正される
      • 受入可能なパラメータの定義セットを持っていることもある
    • いくつかのリソースは、他のプロセスやAPIコールによって修正される
      • 例えば、コアなCO2値を表現しているDataItemが修正されたら、ProfileItemのような、それに関連するアイテムも変更されるだろう
    • PUTすると、関連するHTTPのステータスコードが返ってくる
      • 制限のある(limited)XMLやJSONを返すこともある
  • Deleting resources (DELETE method)
    • リソースは、ユニークなURLを使えば、HTTPのDELETEメソッドで削除することができる
      • 全てのリソースが削除できるわけではない
      • 権限がある場合のみ削除することができる
    • リソースを削除した時
      • 関連する全てのリソースも削除される
      • 他の関連あるリソースは変更される
      • 例えば、ProfileItemを削除したら、関連する全てのProfileItemValuesも削除される
    • DELETEすると、関連するHTTPのステータスコードが返ってくる

AMEE API / Media Types

|

http://my.amee.com/developers/wiki/MediaTypes

  • AMEEにとって、media typesは重要だ(sensitive/影響を受けやすい?)
    • クライアント側の'Accept'ヘッダーは検査され、それに適したレスポンスが生成される
    • 下記のMediaTypesがサポートされている
      • text/html
      • application/json
      • application/xml
    • jsonやxmlを使うときは、それを'Accept'ヘッダに明記する必要がある
      • デフォルトのMediaTypeはtext/html
    • 将来的には、XMLやJSONでリクエストを送れるようにするため、'Content-Type'ヘッダも重要になる

AMEE API / Calculation

|

http://my.amee.com/developers/wiki/Calculation

  • AMEEのAPIは二酸化炭素の排出量を算出する計算機として振る舞う
    • APIには、以下の3つのパーツがある
      • ProfileAPIの中にあるProfileItemResource
      • ProfileAPIの中にあるProfileCategoryResource
      • DataAPIの中にあるDataItemResource
    • それぞれのResouceページを見れば、計算機がどのように振る舞うのかを学べる
    • データの保管場所
      • 計算された二酸化炭素の量は、ProfileItemsのみに保管される
      • Profiles/ProfileCategoriesは履歴情報を持つことができるので、ここに二酸化炭素の量を保管するのは合理的ではない
    • 計算機で使われるデータ
      • ItemDefinitions/ItemValueDefinitions/DataItems/DataItemValues/ProfileItems/ProfileItemValues/Algorithms
Connection: close