ニフクラ mobile backend(mBaaS)お役立ちブログ

スマホアプリ開発にニフクラ mobile backend(mBaaS)。アプリ開発に役立つ情報をおとどけ!

NCMBのREST APIについて

f:id:mbaasdevrel:20210916211516p:plain

ニフクラ 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/(クラス名)/
  • 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

中津川 篤司

中津川 篤司

NCMBエヴァンジェリスト。プログラマ、エンジニアとしていくつかの企業で働き、28歳のときに独立。 2004年、まだ情報が少なかったオープンソースソフトの技術ブログ「MOONGIFT」を開設し、毎日情報を発信している。2013年に法人化、ビジネスとエンジニアを結ぶDXエージェンシー「DevRel」活動をスタート。