さて、今回は基本に返ってkintone REST API を試す方法です。kintone REST APIをJavaやRuby等々外部からコールしたり、kintone JavaScript APIの中でkintone.api()からコールしたりすると思うのですが、デバッグやガッツリ書く前にちょっと試したいなんて時があります。そんな時に役立つREST APIを試す方法を今回次の2通りご紹介します。後者の「POSTMAN」では、先日の「Chromeデベロッパーツールでkintone.api()の動きを確認してみよう！」でご紹介したChromeデベロッパーツールのネットワークタブの話が再登場しますので、合わせてご確認頂ければと思います。
※実はこちらの記事を焼き直したものになります^^;
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'
GET/file – 「ファイルダウンロード」公式リファレンス
curl -X GET 'https://{subdomain}.cybozu.com/k/v1/file.json?fileKey={fileKey}' \
-H 'X-Cybozu-Authorization: {authToken}' \
-o ./{fileName}
しれっと書き並べましたが、・・・少し補足していきましょう。
送信するデータ形式について、通常、-dがついた時にはフォーム形式のデータを送信するのですが、JSON形式にも対応しています。kintone REST APIには直接関係ありませんが、フォーム形式の場合には、データを{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）で共有させて頂いていますので、参考にして頂ければと思います。ファイルのアップロード/ダウンロードも対応していて、最初ちょっと感動しました。
なお、ここでは記述方法とリクエストの中身を見る方法に重きを置きます。また、Chrome内でAdministrator以外のアカウントでログイン中の場合には、APIトークンによる認証はエラーとなりますので、注意が必要です。
- まずは、記載方法とリクエスト方法です
- 次にデバグに役立つリクエストの中身を見る方法です
- リクエストの中身が展開されると次のようになります
展開されたリクエストの中身を拡大してみましょう。
当然のことですが、リクエスト内容が露わになっていることが確認出来ます。
HTTP/REST API/JSONのリクエスト方法を2通り見てきましたが、POSTMANで示したリクエストの中身を展開する方法はデバグ時に有効です。実際のプログラム開発で上手くいかない時には、まずこれを成功させて、リクエスト内容の違いを見比べながらこれと等価なリクエストになるように詰めていくと上手くいくと思います。
弊社ではREST APIやJavascriptAPIを活用したカスタマイズ開発を1週間20万円という定額料金で提供しています。
REST APIを使ったkintoneとの連携開発やカスタマイズ開発でお困りな事がありましたら、弊社までお気軽にお問い合わせください。
