サーバー構築不要！スマートフォンアプリ向けの新クラウド

トップ >ドキュメント >REST API リファレンス:共通フォーマット

このサイトを正しく表示するためには、ブラウザーのJavaScriptの設定を「有効」にしてください。

REST API リファレンス

共通ドキュメント

共通フォーマット

1 REST API について
2 共通仕様
3 共通リクエストヘッダー
4 共通レスポンスヘッダー
5 データ型
6 フィールドの削除について
7 オブジェクトID（objectId）について
8 パーミッション（ACL）について

REST API について

ニフクラ mobile backend は REST API を提供しているため、
外部サーバからデータストアや会員管理・認証などすべての機能をご利用いただけます。

共通仕様

ニフクラ mobile backendのREST APIを利用する際の共通仕様は以下のとおりです。

名前	説明
APIのエンドポイント	mbaas.api.nifcloud.com
APIのバージョン	2013-09-01
使用するプロトコル	HTTPS
文字コード	UTF-8

共通リクエストヘッダー

REST APIをリクエストする場合には、以下の共通リクエストヘッダーが必要です。

ヘッダー名	説明
X-NCMB-Application-Key	アプリケーションキー
X-NCMB-Signature	シグネチャ
X-NCMB-Timestamp	タイムスタンプ
X-NCMB-Apps-Session-Token	アプリセッショントークン

アプリセッショントークン以外は、APIの認証に使用されますので設定が必須です。
アプリセッショントークンはACL制限を行っているデータにアクセスする場合に設定が必要です。

ただし、以下のAPIについてはリクエスト時の認証は行わず、
ワンタイムトークンなどを利用しているため共通リクエストヘッダーの指定が不要です。

メールアドレス確認API
公開ファイル取得API

共通レスポンスヘッダー

サーバーから共通して返却されるHTTPレスポンスヘッダーは、以下のようになります。

ヘッダー名	備考
X-NCMB-Response-Signature	シグネチャ
Content-Type	レスポンスボディのメディアタイプが返却される
Date	日付が返却される
HTTPステータス	成功時には200が返却され、それ以外はエラーコードが返却される
Connection	closeが返却される
Transfer-Encoding	chunked

データ型

REST APIでは、文字列、数値、配列、オブジェクトなどのデータを扱うことができるほか、
以下のような特殊なデータ型も利用可能です。

日付

日付型のフォーマットは以下の通りです。
__typeというフィールドでDateを指定し、isoというフィールドでUTC(協定世界時)の日付を指定します。
タイムゾーンにはUTC以外を設定することはできません。
設定上限は「2038-01-18T23:59:59.999Z」です。

{"__type": "Date", "iso": "YYYY-MM-DDTHH:mm:ss.sssZ"}

※ 上記フォーマットは一例です。環境により異なりますのでご注意ください。

ポインタ

既存のオブジェクトに別オブジェクトを参照するポインタを関連付けることができます。
※ポインタ型の参照では、1つのオブジェクトのみ参照することが可能です。

{"__type":"Pointer","className":"「対象クラス名」","objectId":"「対象オブジェクトID」"}

リレーション

リレーションもポインタと同じように別オブジェクトを参照するためのものですが、
同一クラスに限り一対多の登録も可能になっているものです。

例えば、無料会員と有料会員のロールを作成し、
それぞれのロールに複数の会員を所属させていく
(roleクラスのbelongUserにリレーション型で会員オブジェクトを登録していく)ことで、
無料会員と有料会員でアクセスできるコンテンツを制限することができるようになります。

※ポインタ型は1対1の参照を登録するので、ロールのbelongUserやbelongRoleといったフィールドがポインタ型だった場合は、複数の会員や子ロールを所属させることができません。

リレーション型の登録/取得/削除では、フォーマットが異なっているため、注意が必要です。
以下では、ロールへの会員追加・削除を例にリレーション型の登録/取得/削除の説明を行います。

リレーション型の登録時には、
__op（実行するオペレーション）にAddRelation（リレーションの登録）を指定し、
objectsに参照先となるオブジェクトをポインタ型配列の形式で指定します。

curl -X PUT  -H "X-NCMB-Apps-Session-Token:"\
 -H "X-NCMB-Application-Key:6145f91061916580c742f806bab67649d10f45920246ff459404c46f00ff3e56"\
 -H "X-NCMB-Timestamp:2013-12-02T02:44:35.452Z"\
 -H "X-NCMB-Signature: aBgyshghQuAl6/UY5uAzUzQ4VRB1nUJdpSQixUN5qD4="\
 -H "Content-Type: application/json"\
 -d '{"belongUser":{"__op":"AddRelation", "objects":[{"__type":"Pointer", "className":"user", "objectId":"rvI95wlvkZ5q5vOn"},{"__type":"Pointer", "className":"user", "objectId":"AAA95wlvkZ5q5vOn"}]}}'\
 https://mbaas.api.nifcloud.com/2013-09-01/roles/fA2UG40Xd09KynDp

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://mbaas.api.nifcloud.com/2013-09-01/roles/fA2UG40Xd09KynDp");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "{\"belongUser\":{\"__op\":\"AddRelation\", \"objects\":[{\"__type\":\"Pointer\", \"className\":\"user\", \"objectId\":\"rvI95wlvkZ5q5vOn\"}]}}\n");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");

$headers = array();
$headers[] = "X-NCMB-Apps-Session-Token: ";
$headers[] = "X-NCMB-Application-Key: 6145f91061916580c742f806bab67649d10f45920246ff459404c46f00ff3e56";
$headers[] = "X-NCMB-Timestamp: 2013-12-02T02:44:35.452Z";
$headers[] = "X-NCMB-Signature: aBgyshghQuAl6/UY5uAzUzQ4VRB1nUJdpSQixUN5qD4=";
$headers[] = "Content-Type: application/json";
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
} else {
   print_r($result);
}
curl_close ($ch);

require 'uri'
require 'net/https'

url = URI("https://mbaas.api.nifcloud.com/2013-09-01/roles/fA2UG40Xd09KynDp")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Put.new(url)
request["X-NCMB-Apps-Session-Token"] = nil
request["X-NCMB-Application-Key"] = "6145f91061916580c742f806bab67649d10f45920246ff459404c46f00ff3e56"
request["X-NCMB-Timestamp"] = "2013-12-02T02:44:35.452Z"
request["X-NCMB-Signature"] = "aBgyshghQuAl6/UY5uAzUzQ4VRB1nUJdpSQixUN5qD4="
request["Content-Type"] = "application/json"
request.body = "{\"belongUser\":{\"__op\":\"AddRelation\", \"objects\":[{\"__type\":\"Pointer\", \"className\":\"user\", \"objectId\":\"rvI95wlvkZ5q5vOn\"}]}}"

response = http.request(request)
puts response.body
puts response.code

リレーション型を含むオブジェクトを取得した場合には、__typeにRelationが設定され、
対象のクラス名が設定されている状態で返却されます。

//curlコマンドでのロール取得
curl -X GET -G  -H "X-NCMB-Apps-Session-Token:"\
 -H "X-NCMB-Application-Key:6145f91061916580c742f806bab67649d10f45920246ff459404c46f00ff3e56"\
 -H "X-NCMB-Timestamp:2013-12-02T02:44:35.452Z"\
 -H "X-NCMB-Signature: hNCGJM+ju0RQOdHo+XSe55TUWkJKo2V8RCkKMzXBjXw="\
 -H "Content-Type: application/json"\
 --data-urlencode 'where={"belongUser":{"__type":"Pointer", "className":"user", "objectId":"rvI95wlvkZ5q5vOn"}}'\
 https://mbaas.api.nifcloud.com/2013-09-01/roles

 //コマンドを実行した結果、belongUserがリレーション型であることが分かる
{
   "results":[
      {
         "objectId":"fA2UG40Xd09KynDp",
         "roleName":"testRole",
         "belongRole":null,
         "belongUser":{
            "__type":"Relation",
            "className":"user"
         },
         "createDate":"2014-06-02T02:56:55.577Z",
         "updateDate":"2014-06-02T03:14:51.186Z",
         "acl":{
            "*":{
               "read":true,
               "write":true
            }
         }
      }
   ]
}

//phpコマンドでのロール取得
$ch = curl_init();

$url = "https://mbaas.api.nifcloud.com/2013-09-01/roles";
$param_value = "{\"belongUser\":{\"__type\":\"Pointer\", \"className\":\"user\", \"objectId\":\"rvI95wlvkZ5q5vOn\"}}";
$hash = [];
$hash['where'] = $param_value;
$url = sprintf("%s?%s", $url, http_build_query($hash, null, null, PHP_QUERY_RFC3986));
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

$headers = array();
$headers[] = "X-NCMB-Apps-Session-Token: ";
$headers[] = "X-NCMB-Application-Key: 6145f91061916580c742f806bab67649d10f45920246ff459404c46f00ff3e56";
$headers[] = "X-NCMB-Timestamp: 2013-12-02T02:44:35.452Z";
$headers[] = "X-NCMB-Signature: hNCGJM+ju0RQOdHo+XSe55TUWkJKo2V8RCkKMzXBjXw=";
$headers[] = "Content-Type: application/json";
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
} else {
    print_r($result);
}
curl_close($ch);

 //コマンドを実行した結果、belongUserがリレーション型であることが分かる
{
   "results":[
      {
         "objectId":"fA2UG40Xd09KynDp",
         "roleName":"testRole",
         "belongRole":null,
         "belongUser":{
            "__type":"Relation",
            "className":"user"
         },
         "createDate":"2014-06-02T02:56:55.577Z",
         "updateDate":"2014-06-02T03:14:51.186Z",
         "acl":{
            "*":{
               "read":true,
               "write":true
            }
         }
      }
   ]
}

//rubyコマンドでのロール取得
require 'uri'
require 'net/https'

param_value = "{\"belongUser\":{\"__type\":\"Pointer\", \"className\":\"user\", \"objectId\":\"rvI95wlvkZ5q5vOn\"}}"
encoded_param_value = URI.encode_www_form_component(param_value).gsub("+", "%20").strip
url = URI("https://mbaas.api.nifcloud.com/2013-09-01/roles?where="+encoded_param_value)
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["X-NCMB-Apps-Session-Token"] = nil
request["X-NCMB-Application-Key"] = "6145f91061916580c742f806bab67649d10f45920246ff459404c46f00ff3e56"
request["X-NCMB-Timestamp"] = "2013-12-02T02:44:35.452Z"
request["X-NCMB-Signature"] = "hNCGJM+ju0RQOdHo+XSe55TUWkJKo2V8RCkKMzXBjXw="
request["Content-Type"] = "application/json"

response = http.request(request)
puts response.body
puts response.code

 //コマンドを実行した結果、belongUserがリレーション型であることが分かる
{
   "results":[
      {
         "objectId":"fA2UG40Xd09KynDp",
         "roleName":"testRole",
         "belongRole":null,
         "belongUser":{
            "__type":"Relation",
            "className":"user"
         },
         "createDate":"2014-06-02T02:56:55.577Z",
         "updateDate":"2014-06-02T03:14:51.186Z",
         "acl":{
            "*":{
               "read":true,
               "write":true
            }
         }
      }
   ]
}

リレーション型で紐付けされた方のオブジェクトを取得する場合には、$relatedToオペレータを使用して、
紐付けられた方のオブジェクト検索を行います。今回の場合、会員のオブジェクトがロールに紐付けされているので、
会員検索時に、「roleクラスにあるobjectIdがfA2UG40Xd09KynDpのオブジェクトにて、
belongUserというキーに紐付いている会員」という検索条件を設定します。

//$relatedToオペレータを使用した会員検索のcurlコマンド
curl -X GET -G  -H "X-NCMB-Apps-Session-Token:"\
 -H "X-NCMB-Application-Key:6145f91061916580c742f806bab67649d10f45920246ff459404c46f00ff3e56"\
 -H "X-NCMB-Timestamp:2013-12-02T02:44:35.452Z"\
 -H "X-NCMB-Signature: 8TE7W/N8YegXxJLJGV1N7FpaMdSxi943edYI71r+9B8="\
 -H "Content-Type: application/json"\
 --data-urlencode 'where={"$relatedTo":{"object":{"__type":"Pointer", "className":"role","objectId":"fA2UG40Xd09KynDp"},"key":"belongUser"}}'\
 https://mbaas.api.nifcloud.com/2013-09-01/users

//curlコマンドで得られる結果
{
   "results":[
      {
         "objectId":"rvI95wlvkZ5q5vOn",
         "userName":"testUser",
         "authData":null,
         "mailAddress":null,
         "mailAddressConfirm":null,
         "createDate":"2014-06-02T02:56:25.350Z",
         "updateDate":"2014-06-02T03:17:47.389Z",
         "acl":{
            "rvI95wlvkZ5q5vOn":{
               "read":true,
               "write":true
            },
            "*":{
               "read":true,
               "write":true
            }
         }
      }
   ]
}

//$relatedToオペレータを使用した会員検索のphpコマンド
$ch = curl_init();

$url = "https://mbaas.api.nifcloud.com/2013-09-01/users";
$param_value = "{\"\$relatedTo\":{\"object\":{\"__type\":\"Pointer\", \"className\":\"role\",\"objectId\":\"fA2UG40Xd09KynDp\"},\"key\":\"belongUser\"}}";
$hash = [];
$hash['where'] = $param_value;
$url = sprintf("%s?%s", $url, http_build_query($hash, null, null, PHP_QUERY_RFC3986));
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

$headers = array();
$headers[] = "X-NCMB-Apps-Session-Token: ";
$headers[] = "X-NCMB-Application-Key: 6145f91061916580c742f806bab67649d10f45920246ff459404c46f00ff3e56";
$headers[] = "X-NCMB-Timestamp: 2013-12-02T02:44:35.452Z";
$headers[] = "X-NCMB-Signature: 8TE7W/N8YegXxJLJGV1N7FpaMdSxi943edYI71r+9B8=";
$headers[] = "Content-Type: application/json";
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
} else {
    print_r($result);
}
curl_close($ch);

//phpコマンドで得られる結果
{
   "results":[
      {
         "objectId":"rvI95wlvkZ5q5vOn",
         "userName":"testUser",
         "authData":null,
         "mailAddress":null,
         "mailAddressConfirm":null,
         "createDate":"2014-06-02T02:56:25.350Z",
         "updateDate":"2014-06-02T03:17:47.389Z",
         "acl":{
            "rvI95wlvkZ5q5vOn":{
               "read":true,
               "write":true
            },
            "*":{
               "read":true,
               "write":true
            }
         }
      }
   ]
}

//$relatedToオペレータを使用した会員検索のrubyコマンド
require 'uri'
require 'net/https'

param_value = "{\"\$relatedTo\":{\"object\":{\"__type\":\"Pointer\", \"className\":\"role\",\"objectId\":\"fA2UG40Xd09KynDp\"},\"key\":\"belongUser\"}}"
encoded_param_value = URI.encode_www_form_component(param_value).gsub("+", "%20").strip
url = URI("https://mbaas.api.nifcloud.com/2013-09-01/users?where="+encoded_param_value)
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["X-NCMB-Apps-Session-Token"] = nil
request["X-NCMB-Application-Key"] = "6145f91061916580c742f806bab67649d10f45920246ff459404c46f00ff3e56"
request["X-NCMB-Timestamp"] = "2013-12-02T02:44:35.452Z"
request["X-NCMB-Signature"] = "8TE7W/N8YegXxJLJGV1N7FpaMdSxi943edYI71r+9B8="
request["Content-Type"] = "application/json"

response = http.request(request)
puts response.body
puts response.code

//rubyコマンドで得られる結果
{
   "results":[
      {
         "objectId":"rvI95wlvkZ5q5vOn",
         "userName":"testUser",
         "authData":null,
         "mailAddress":null,
         "mailAddressConfirm":null,
         "createDate":"2014-06-02T02:56:25.350Z",
         "updateDate":"2014-06-02T03:17:47.389Z",
         "acl":{
            "rvI95wlvkZ5q5vOn":{
               "read":true,
               "write":true
            },
            "*":{
               "read":true,
               "write":true
            }
         }
      }
   ]
}

ある会員をロールから削除する場合など、リレーション型で紐付けされたオブジェクトへの参照を削除する場合は、
__op（実行するオペレーション）でRemoveRelation（リレーションの削除）を指定します。

//リレーションの削除を行うcurlコマンド
curl -X PUT  -H "X-NCMB-Apps-Session-Token:"\
 -H "X-NCMB-Application-Key:6145f91061916580c742f806bab67649d10f45920246ff459404c46f00ff3e56"\
 -H "X-NCMB-Timestamp:2013-12-02T02:44:35.452Z"\
 -H "X-NCMB-Signature: aBgyshghQuAl6/UY5uAzUzQ4VRB1nUJdpSQixUN5qD4="\
 -H "Content-Type: application/json"\
 -d '{"belongUser":{"__op":"RemoveRelation", "objects":[{"__type":"Pointer", "className":"user", "objectId":"rvI95wlvkZ5q5vOn"}]}}'\
 https://mbaas.api.nifcloud.com/2013-09-01/roles/fA2UG40Xd09KynDp

//リレーションの削除を行うphpコマンド
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://mbaas.api.nifcloud.com/2013-09-01/roles/fA2UG40Xd09KynDp");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "{\"belongUser\":{\"__op\":\"RemoveRelation\", \"objects\":[{\"__type\":\"Pointer\", \"className\":\"user\", \"objectId\":\"rvI95wlvkZ5q5vOn\"}]}}\n");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");

$headers = array();
$headers[] = "X-NCMB-Apps-Session-Token: ";
$headers[] = "X-NCMB-Application-Key: 6145f91061916580c742f806bab67649d10f45920246ff459404c46f00ff3e56";
$headers[] = "X-NCMB-Timestamp: 2013-12-02T02:44:35.452Z";
$headers[] = "X-NCMB-Signature: aBgyshghQuAl6/UY5uAzUzQ4VRB1nUJdpSQixUN5qD4=";
$headers[] = "Content-Type: application/json";
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
} else {
   print_r($result);
}
curl_close ($ch);

//リレーションの削除を行うrubyコマンド
require 'uri'
require 'net/https'

url = URI("https://mbaas.api.nifcloud.com/2013-09-01/roles/fA2UG40Xd09KynDp")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Put.new(url)
request["X-NCMB-Apps-Session-Token"] = nil
request["X-NCMB-Application-Key"] = "6145f91061916580c742f806bab67649d10f45920246ff459404c46f00ff3e56"
request["X-NCMB-Timestamp"] = "2013-12-02T02:44:35.452Z"
request["X-NCMB-Signature"] = "aBgyshghQuAl6/UY5uAzUzQ4VRB1nUJdpSQixUN5qD4="
request["Content-Type"] = "application/json"
request.body = "{\"belongUser\":{\"__op\":\"RemoveRelation\", \"objects\":[{\"__type\":\"Pointer\", \"className\":\"user\", \"objectId\":\"rvI95wlvkZ5q5vOn\"}]}}"

response = http.request(request)
puts response.body
puts response.code

位置情報

緯度／経度で位置情報を示します。
※指定可能な範囲は、経度：-180～180、緯度：-90～90となっています。

{"__type":"GeoPoint","longitude":「経度」,"latitude":「緯度」}

位置情報型が指定されたフィールドに対して、その他の型のデータで登録／更新を実施すると「E403006」のエラーが返却されます。
その他のデータ型が指定されたフィールドに対して、位置情報型データで登録／更新を実施した場合も同様です。

フィールドの削除について

値にnullを指定してレコード（オブジェクト）を更新することで、そのフィールドの値を削除することができます。

オブジェクトID（objectId）について

各クラスのオブジェクトを管理するために自動生成された一意な文字列です.
操作対象のオブジェクトを一意に特定するために利用します.
例）更新API、削除API、取得APIのパスの構成要素として利用します.

パーミッション（ACL）について

mobile backendには、クラスのパーミッションとレコード（オブジェクト）のパーミッションがあります。
これらのパーミッションは、会員やロールに対して権限を追加していくACLの形式で設定されます。
設定できる権限の種類は以下の通りです。

ACLの種類	設定可能な値
クラスのACL (管理画面から設定可能)	get（取得）, find（検索）, update（更新）, create（作成）, delete（削除）, add fields（フィールド追加）
レコードのACL (管理画面とアプリから設定可能)	read（読み込み）, write（書き込み・削除）

ACL未指定時の初期値は、システム側であらかじめ設定されている以下のデフォルト値になります。
　　会員を登録する場合　：　会員本人のみが読み・書き可能
　　上記以外の場合　　　：　個別設定なし（フルアクセス可能）

オブジェクトのACLに対して、nullや{} （空オブジェクト）を指定した場合はフルアクセス可能となりますのでご注意ください。

ACLの記載例

会員にオブジェクトのACLを指定する

{ "acl" : { "4suSlFT5xx" : { "read" : true , "write": true } } }

ロールにACLを指定する

{ "acl" : { "role:admin" : { "read" : true , "write": true } } }

ある会員にのみ、書き込み権限を指定する

{ "acl" : { "*" : { "read" : true } , "4suSlFT5xx" : { "read" : true , "write" : true } } }

ある会員に、読み込みのみの権限を指定する

{ "acl" : { "*" : { "read" : true , "write" : true } , "4suSlFT5xx" : { "read" : true } } }

お探しの内容が見つからなかった場合はユーザーコミュニティもご活用ください。（回答保証はいたしかねます）
なお、 Expertプラン以上のお客様はテクニカルサポートにてご質問を承らせて頂きます。

推奨画面サイズ1024×768px以上

ページの先頭へ