kintoneで学ぶREST APIのリクエスト方法(テスト/デバグ用)
今回は「REST API」のリクエスト方法について、APIのテストやデバグで活用出来るように、サイボウズkintoneを題材に自分の備忘録的な情報をまとめておきたいと思います。
kintoneを題材にしているのは、「REST API」、「JSON形式」といったトレンドの設計にのっかていること、ファイルのアップロード/ダウンロードを扱っていることから、網羅的に整理出来ることが大きいです。「kintone REST API」が扱えれば他のWebサービスのリクエストも扱えるという考えです。
※「kintone REST API」の公式リファレンスはこちらです
【curlコマンド】
まずはcurlコマンドです。メソッドを一通り網羅することを目的とすることから、次のリクエスト例はkintone REST APIの一部になりますので、ご了承ください。
なお、{subdomain}
、{apiToken}
、{authToken}
は、各自置き換えてください。認証については、要件に応じてX-Cybozu-Authorization
、X-Cybozu-API-Token
を使い分けてください。
- GET/record(クエリ利用)- 「レコード取得」公式リファレンス
-
curl -X GET "https://{subdomain}.cybozu.com/k/v1/record.json?app=610&id=1" \
-H "X-Cybozu-API-Token: {apiToken}"
- GET/record(ボディ利用)- 「レコード取得」公式リファレンス
-
curl -X GET "https://{subdomain}.cybozu.com/k/v1/record.json" \
-H "X-Cybozu-API-Token: {apiToken}" \
-H "Content-Type:application/json" \
-d "{"app": 610,"id": 1340}"
- POST/record - 「レコード登録」公式リファレンス
-
curl -X POST "https://{subdomain}.cybozu.com/k/v1/record.json" \
-H "X-Cybozu-API-Token: {apiToken}" \
-H "Content-Type:application/json" \
-d "{"app": 610,"record": {"tempC":{"value":210}}}"
- PUT/record - 「レコード更新」公式リファレンス
-
curl -X PUT "https://{subdomain}.cybozu.com/k/v1/record.json" \
-H "X-Cybozu-API-Token: {apiToken}" \
-H "Content-Type:application/json" \
-d "{"app": 610, "id":1344, "record": {"tempC":{"value":21}}}" - DELETE/records(ボディ利用) - 「レコード削除」公式リファレンス
-
curl -X DELETE "https://{subdomain}.cybozu.com/k/v1/records.json" \
-H "X-Cybozu-API-Token: {apiToken}" \
-H "Content-Type:application/json" \
-d "{"app": 610, "ids":[1344, 1343]}" - POST/file - 「ファイルアップロード」公式リファレンス
-
curl -X POST "https://{subdomain}.cybozu.com/k/v1/file.json" \
-H "X-Cybozu-Authorization: {authToken}" \
-F "file=@sample.txt"
しれっと書き並べましたが、・・・少し考察しましょう。
送信するデータ形式について、通常、-d
がついた時にはフォーム形式のデータを送信するのですが、JSON形式にも対応しています。フォーム形式の場合には、データを{key}={value}
の形式で記述することになり、Content-Type:application/x-www-form-urlencoded
がヘッダとして自動付加されます。一方JSON形式の場合には、上記の通りデータは文字列での記載となり、Content-Type:application/json
をヘッダで指定する必要があります。
また、ファイルをデータ送信する際には、-d
に代わって-F
を利用します。対応するMIMEタイプはContent-Type:multipart/form-data
ですが、明示は不要(自動付加)のようです。
更に、curlコマンドの特徴の一つは、GETやDELETEのメソッドでボディを送信出来ることではないでしょうか。開発言語やライブラリ次第かと思いますが、これが出来ないものは結構多いです。後述のPOSTMANでも唯一これはできないといったような機能です。ここで合わせて注意しておきたいのは、kintoneのGETメソッドではオプションパラメータをURIクエリもしくはボディで指定する方法がありますが、ボディ利用時にはJSONで記述されることを明示するため、Content-Type:application/json
をヘッダで指定する必要がある一方で、クエリ利用時にはMIMEタイプの指定は不要(エラー)になる点です。
ちなみに、コマンドラインでkintoneを使い倒すためには「kintone-ci」が公開されていますので、こちらをご利用ください。
【POSTMAN(ブラウザHTTPクライアント)】
次にchrome extentionで提供されるHTTPクライアント、POSTMANです。POSTMANは、JSON形式からファイルの取扱いまで、あらゆるAPIの試験が可能で、コレクションとして個々のリクエストを保存出来ますので、非常に便利です。出来ないことがあるとすれば、唯一GETやDELETEのメソッドでボディが送信出来ないくらいです。
kintoneの基本的なAPIリクエストのコレクションはこちら(文字コードUTF−8)で共有させて頂いていますので、参考にして頂ければと思います。
なお、ここでは記述方法とリクエストの中身を見る方法に重きを置きます。
- まずは、記載方法とリクエスト方法です
- 次にデバグに役立つリクエストの中身を見る方法です
- リクエストの中身が展開されると次のようになります
展開されたリクエストの中身を拡大してみましょう。
当然のことですが、リクエスト内容が露わになっていることが確認出来ます。
HTTP/REST API/JSONのリクエスト方法を2通り見てきましたが、POSTMANで示したリクエストの中身を展開する方法はデバグ時に有効です。実際のプログラム開発で上手くいかない時には、まずこれを成功させて、リクエスト内容の違いを見比べながらこれと等価なリクエストになるように詰めていくと上手くいきます。
kintoneに限らず、Web-APIを利用した開発時にお役立て頂ければ幸いです。