ニフクラ mobile backendでは基本的な操作をすべてREST APIで提供しています。SDKから利用している限りはあまり気を遣う必要はないのですが、利用する言語向けにSDKがなかったり、ちょっとした操作をREST API経由で行いたいこともあるでしょう。
そこで今回はNCMBのREST APIの種類について紹介します。
REST APIの仕組み
REST APIというのは、URLのパスで操作対象を、HTTPメソッドで操作内容を指定する仕組みです。NCMBも他のREST APIを提供するサービスと同じく、HTTPメソッドごとに次のように分かれています。
- GET
データ取得 - POST
データ作成 - PUT
データ更新 - DELETE
データ削除
例えばデータストアの操作をする場合、/2013-09-01/classes/(クラス名)/ というのが共通パスになります。
- GET
- データを1件取得
/2013-09-01/classes/(クラス名)/(オブジェクトID) - データを検索（複数件取得） /2013-09-01/classes/(クラス名)/
- データを1件取得
- POST
- データを新規作成
/2013-09-01/classes/(クラス名)/
- データを新規作成
- PUT
- データを更新 /2013-09-01/classes/(クラス名)/(オブジェクトID)
- DELETE
- データを削除 /2013-09-01/classes/(クラス名)/(オブジェクトID)
データを新規作成する場合には対象となるリソース（objectId）がないので、クラス名までを指定します。データの更新や削除の場合は対象となるデータを指定するので、objectIdまでを指定します。GETはデータを1件だけ取得する場合と、複数件取得する場合があるので、URLも2パターンあります。
特殊な操作
REST APIだけでは足りない操作があり、その場合には専用のURLが用意されます。
- 会員登録メール要求
POST /2013-09-01/requestMailAddressUserEntry - 会員ログイン
GET /2013-09-01/login - 会員ログアウト
GET /2013-09-01/logout - メールアドレス確認
GET /2013-09-01/applications/アプリケーションID/mailAddressConfirm?token=ONE_TIME_TOKEN - パスワード再発行登録
POST /2013-09-01/requestPasswordReset - プッシュ通知開封登録
POST /2013-09-01/push/プッシュ通知ID/openNumber
署名生成処理で注意するのはGET
NCMBへリクエストする際には署名を生成してヘッダーにセットすることで、そのリクエストの正当性を証明します。この時、署名生成に使われるのは次の情報です。
- 固定情報
- アプリケーションキー
- シグネチャメソッド
- シグネチャバージョン
- FQDN
- 可変情報
- リクエストメソッド
- リクエストしたAPIのパス
- クエリストリング
- タイムスタンプ
この時、タイムスタンプとクエリストリング（検索条件）はリクエストごとに頻繁に変わる情報になるでしょう。データの作成、更新、削除はクエリストリングを指定しませんので、タイムスタンプだけ注意すれば、正しい署名が生成できるはずです。
GETリクエストの場合には、検索条件を正しく並べ替えて、エンコーディングする必要があります。詳細はREST API リファレンス : シグネチャの生成方法 | ニフクラ mobile backendをご覧ください。
検索条件で注意するのはwhere
データストアや会員情報、ファイルストアなどを検索する際にはクエリ条件を指定できます。条件は次のようになります。
- where
データの値などを使って対象を絞り込みます - limit
データの取得件数を指定します - skip データを読み飛ばす件数を指定します
- order データの並び順を指定します
- count 検索結果に対象データの総件数を追加します
- include
指定したポインターデータも取得します
whereを除けば、他は数値または文字列で条件を指定します。そのためクエリストリングとして指定する際にも、URLエンコーディングはほとんど問題になりません。
whereは条件がJSONオブジェクト形式なので注意してください。例えば次のようになります。
{ "score": { "$gte": 1000, "$lte":3000 }, "arrayKey": { "$all": [2, 3, 4] } }
この時、: { のように間にスペースが入った状態でエンコーディングを行うと、不正な署名が生成されます。改行やスペースのないJSON文字列を作り、それをエンコードする必要があります。
まとめ
まとめると、NCMBのREST APIの特徴は次のようになります。
- 基本はRESTful（リソースをURL、処理をHTTPメソッドで指定）
- いくつかRESTの原則に当てはまらないAPIがある（ログインなど）
- 署名はGET以外は難しくはない
- where条件のエンコーディングに注意
REST APIを直接触れるケースは多くないと思いますが、何度かコミュニティに質問が上がることもあります。直接REST APIを呼び出す場合には、こちらの記事を参考にしてください。
REST API リファレンス : 共通フォーマット | ニフクラ mobile backend
