2016年5月30日月曜日

RESTコントロールを使いこなそう!(2)

前回の続きです。

RESTコントロールを使いこなそう 連載

今回は、前置きとしてWebAPIのことについて少し説明します。

HTTPのメソッドについて

メソッドというのは、HTTPリクエストを送る際にリクエストがどういう目的なのかを示したものです。

主なメソッドだけ抜き出します。

  • GET ... リソースの取得
  • POST ... リソースの作成、追加(*1)
  • PUT ... リソースの更新(*1)
  • DELETE ... リソースの削除

*1 POSTとPUTは実は別な理由で使い分けしますが、おおよそこのように使い分けて問題ありません。

参考: POSTとPUTの使い分け

見てピンときたかもしれません。HTTPのメソッドでCRUDが表現できるのです。

WebAPIの設計においては、このメソッドを意識してサービスを提供しなくてはなりません。

URLについて

RESTを設計する場合、URLにも気を配ります。

原則として、URLにはリソース名を含めるようにし、アクションは含めません。

よって下のようなURLはRESTの原則からすると、NGとなります。

http://192.168.1.1/hoge.nsf/api.xsp/documents/save?docId=xxxxxxx-xxxx-xxxxx

save は更新を意味するでしょうから、下記URLとしてPUTメソッドで受け付けるようにします。

http://192.168.1.1/hoge.nsf/api.xsp/documents/xxxxxxx-xxxx-xxxxx/

リソースの種類を示す、documents と特定のリソースを示すIDをURLに含めています。

リソースの種類は複数形で示すのが通例です。

詳しいRESTの設計については、↓を参考にしてください。

developerWorks 日本語版: RESTful Web サービスの基本

GETサービスを作る

さて、Domino Designerに戻って、処理を書いていきましょう。

まずは、Q&Aの質問の一覧を取得するためのサービスを書いていきます。

カテゴリで絞ることができるようにします。 カテゴリの指定は、URLのクエリパラメータで渡すことにします。

http://192.168.1.1/hoge.nsf/api.xsp/documents?category=xpages

RESTコントロールの、"全てのプロパティ" > "service" > "doGet" に必要なデータを取得するコードを書くのですが、主要な処理はここではスクリプトライブラリに書くこととします。

// QuestionAPI.jss
var QuestionApi = {
 GetList: function(category){
  var qaDb = session.getDatabase('','ebihara/qa9.nsf');
  var docView:NotesView = qaDb.getView('V_Date_All_Cate');
  var docs:NotesDocumentCollection;
  var array = []; //返すJSONのオブジェクト配列を定義
  var doc:NotesDocument;
  if(!!category){
    docs = docView.getAllDocumentsByKey(category);
  }else{
   docs = docView;
  }
  var doc = docs.getFirstDocument();
  while(doc != null){
   var status = doc.getItemValueString('Status');
   var tagsVector = doc.getItemValue('Tag');
   
   var obj = {
    title: doc.getItemValueString('Title'),
    //JSONに日付型は無いのでUnixTimeを利用する
    createDatetime: doc.getCreated().toJavaDate().getTime(),
    tags: VectorToStringArray(tagsVector),
    status: (status === '1') ? 'unsolved' : 'solved'
   };
   array.push(obj);
   doc = docs.getNextDocument(doc);
  }
  // JavascriptオブジェクトをJSON文字列に変換して返する
  return toJson(array); 
 }
};

function VectorToStringArray(vector){
 var _vector:java.util.Vector = vector;
 var ret = [];
 for(var i=_vector.size()-1; 0 <= i; i--){
  ret.push(_vector[i]);
 }
 return ret;
}

この関数では、

  1. 引数のカテゴリに一致する文書をビューから取得。
  2. "obj"というオブジェクトに文書の内容を作成。
  3. "array"に"obj"を格納。
  4. "array"をtoJson()でJSON文字列に変換して返す。

ということを行っています。

この関数を利用する、RESTコントロールのdoGetはこんな感じ

var category = param.get('category');
return QuestionApi.GetList(category);

ここでは、URLのパラメータ"category"の値を取得し、 上の関数に渡して、帰ってきたJSON文字列を返しているだけです。

上で説明したように、カテゴリはURLのパラメータで渡されます。 それを取得するには、"param.get()"で簡単に取得することができます。

URLの文字列を自前で分析する必要はありません。

また、パラメータの値として記号や日本語などのマルチバイト文字を入れる場合、URLエンコードする必要があり、取得する際にデコードが必要になりますが、"param.get()"を利用することで デコードまで自動で処理を行ってくれます。

テスト

これでREST APIが完成したのですが、試してみたいですよね?

ブラウザでURLを叩いてもいいのですが、RESTコンソールアプリを使うと確認が非常に楽です。

これについては、次々回になると思いますが、別途説明します。

さらに次回へ

次はPOSTでのデータの登録を実装してみたいと思います。

0 件のコメント:

コメントを投稿