AMEE API / API Operations

AMEE

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のステータスコードが返ってくる