APICloud数据云API文档.docx
《APICloud数据云API文档.docx》由会员分享，可在线阅读，更多相关《APICloud数据云API文档.docx（12页珍藏版）》请在冰豆网上搜索。
APICloud数据云API文档
RESTAPI详解
RestfulAPI可以让您用任何可以发送http请求的设备来与APICloud进行交互,您可以使用RestfulAPI做以下事情,例如:
·一个移动网站可以通过Javascript来获取APICloud上的数据.
·一个网站可以展示来自APICloud的数据。
·您可以上传大量的数据,之后可以被一个移动app读取。
·使用任何语言写的程序都可以操作APICloud上的数据。
·如果您不再需要使用APICloud，您可以导出您所有的数据。
API版本
·1.0版本：
2014年9月15日发布。
快速参考
所有的API访问都是通过HTTP进行的。
相关API访问需要在 下。
对象
URL
HTTP
功能
/mcm/api/
POST
创建对象
/mcm/api//
GET
获取对象
/mcm/api//
PUT
更新对象
/mcm/api/
GET
查询对象
/mcm/api//
DELETE
删除对象
用户
URL
HTTP
功能
/mcm/api/user/
POST
新增用户
/mcm/api/user/login
GET
登录
/mcm/api/user/logout
GET
登出
/mcm/api/user/verifyEmail
POST
发送验证邮件
/mcm/api/user/resetRequest
POST
密码重置
/mcm/api/user/
GET
获取用户
/mcm/api/user/
PUT
更改用户信息
/mcm/api/user/
DELETE
删除用户
角色
URL
HTTP
功能
/mcm/api/role
POST
创建角色
/mcm/api/role/
GET
获取角色
/mcm/api/role/
PUT
更新角色
/mcm/api/role/
DELETE
删除角色
请求验证
当调用APICloud云开发接口时，我们需要对头部信息中X-APICloud-AppKey进行验证，X-APICloud-AppKey的生成规则如下：
yourappkey=SHA1（你的应用ID+'UZ'+你的应用KEY+'UZ'+当前时间毫秒数）.当前时间毫秒数
例如：
你的应用ID是A6968565094002，而你的应用KEY是62FB16B2-0ED6-B460-1F60-EB61954C823B，则你在请求头部信息X-APICloud-AppKey中设置的值应为A6968565094002+’UZ’+62FB16B2-0ED6-B460-1F60-EB61954C823B+’UZ’+当前时间毫秒数组合字符串后通过SHA1加密后返回的字符串＋.当前时间毫秒数。
示例代码如下：
varnow=Date.now（）;varappKey=sha1（“A6968565094002+”UZ”+”62FB16B2-0ED6-B460-1F60-EB61954C823B”+UZ+now）+”.”+now
请求格式
对于POST和PUT请求，请求的主体必须是JSON格式，而且HTTPheader的Content-Type需要设置为application/json。
用户验证是通过HTTPheader来进行的。
X-APICloud-AppId头标明正在运行的是哪个App程序，而X-APICloud-AppKey头用来授权鉴定终端。
对于Javascript使用，APICloud支持跨域资源共享，所以您可以将这些header同XMLHttpRequest一同使用。
响应格式
对于所有的请求的响应格式都是一个JSON对象。
一个请求是否成功是由HTTP状态码标明的。
一个2XX的状态码表示成功，而一个4XX表示请求失败。
当一个请求失败时响应的主体仍然是一个JSON对象，但是总是会包含code。
您可以用它们来进行调试。
对象
对象格式
通过RESTAPI保存数据需要将对象的数据通过JSON来编码。
这个数据是无模式化的（SchemaFree），这意味着您不需要提前标注每个对象上有那些key。
您只需要随意设置key-value对就可以，后端会存储它的。
举个例子，假设您准备设置一个公司信息。
一个简单的对象可能包含：
{"name":
"APICloud","level":
"Branch","area":
"HaidianDistrict"}
Key必须是字母和数字组成的String，Value可以是任何可以JSON编码的东西。
每个对象都有一个类名，您可以通过类名来区分不同的数据。
例如,我们可以把公司对象称之为Company。
我们推荐您使用NameYourClassesLikeThis和nameYourKeysLikeThis这样的格式为您的Key-Value命名，可以使您的代码看起来很漂亮。
当您从APICloud中获取对象时，一些字段会被自动加上：
createdAt，updatedAt和objectID。
这些字段的名字是保留的，您不能自行设置它们。
我们上面设置的对象在获取时应该是下面的样子。
{"name":
"APICloud","level":
"Branch","area":
"HaidianDistrict"，"createAt":
"2014-08-20T02:
06:
57.931Z","updateAt":
"2014-08-20T02:
06:
57.931Z","objectId":
"5436219ea1a14d1c60de3e05"}
createdAt和updatedAt都是UTC时间戳，以ISO8601标准和毫秒级精度储存：
YYYY-MM-DDTHH:
MM:
SS.MMMMZ。
objectId是一个string，在类中唯一标明了一个对象。
在RESTAPI中class级的在一个资源上的操作只会根据类名来进行。
例如，如果类名是Company，那么class的URL就是http:
//
针对于一个特定的对象的操作可以通过组织一个URL来做。
例如，对Company中的一个objectId为5436219ea1a14d1c60de3e05的对象的操作应使用如下URL：
创建对象
为了在APICloud上创建一个新的对象，应该向class的URL发送一个POST请求，其中应该包含对象本身。
例如，要创建如上对象：
curl-XPOST\-H"X-APICloud-AppId:
{{your_app_id}}"\-H"X-APICloud-AppKey:
{{your_app_key}}"\-H"Content-Type:
application/json"\-d'{"name":
"APICloud","level":
"Branch","area":
"HaidianDistrict"}'\
当创建成功时，HTTP的返回Code是200，响应的主体是一个JSON对象，包含新的对象的objectId，createdAt和updateAt时间戳。
{"id":
"5436442ca1a14d1c60de3e06","name":
"APICloud","level":
"Branch","area":
"HaidianDistrict","createdAt":
"2014-10-09T08:
15:
40.843Z","updatedAt":
"2014-10-09T08:
15:
40.843Z"}
获取对象
当你创建了一个对象时，你可以通过发送一个GET请求以获取它的内容。
例如，为了得到我们上面创建的对象：
curl-XGET\-H"X-APICloud-AppId:
{{your_app_id}}"\-H"X-APICloud-AppKey:
{{your_app_key}}"\
返回的主体是一个JSON对象包含所有用户提供的字段加上createdAt，updatedAt和objectId字段：
{"id":
"5436442ca1a14d1c60de3e06","name":
"APICloud","level":
"Branch","area":
"HaidianDistrict","createdAt":
"2014-10-09T08:
15:
40.843Z","updatedAt":
"2014-10-09T08:
15:
40.843Z"}
更改对象
为了更改一个对象上已经有的数据，您可以发送一个PUT请求到对象相应的URL上，任何您未指定的key都不会更改，所以您可以只更新对象数据的一个子集。
例如，我们来更改我们对象的一个area的字段：
curl-XPUT\-H"X-APICloud-AppId:
{{your_app_id}}"\-H"X-APICloud-AppKey:
{{your_app_key}}"\-H"Content-Type:
application/json"\-d'{"area":
"DongchengDistrict"}'\
返回的主体是一个JSON对象包含所有用户提供的字段加上createdAt，updatedAt和objectId字段，其中updatedAt为最新的UTC更新时间戳。
{"id":
"5436442ca1a14d1c60de3e06","name":
"APICloud","level":
"Branch","area":
"DongchengDistrict","createdAt":
"2014-10-09T08:
15:
40.843Z","updatedAt":
"2014-10-09T08:
34:
28.153Z"}
删除对象
为了在APICloud中删除一个对象，可以发送一个DELETE请求到指定的对象的URL，比如：
curl-XDELETE\-H"X-APICloud-AppId:
{{your_app_id}}"\-H"X-APICloud-AppKey:
{{your_app_key}}"\
数据类型
在APICloud中创建对象时，相关对象字段数据类型可以被定义为以下十种的任何一种，相关支持数据类型如下：
·String
·Number
·Boolean
·Date
·File
·Array
·Object
·GeoPoint
·Pointer
·Relation
用户
新增用户
注册一个新用户时username、password两个字段都是必要的。
password字段会以和其他的字段不一样的方式处理，它在储存时会被加密而且永远不会被返回给任何来自客户端的请求。
为了新增一个用户，需要向user路径发送一个POST请求，示例如下:
curl-XPOST\-H"X-APICloud-AppId:
{{your_app_id}}"\-H"X-APICloud-AppKey:
{{your_app_key}}"\-H"Content-Type:
application/json"\-d'{"username":
"apicloud","password":
"123456","email":
"test@"}'\
如果创建成功，返回的状态码是200，返回的主体是一个JSON对象，包含objectId,createdAt和updatedAt等属性信息，示例如下：
{"createdAt":
"2014-10-14T07:
16:
29.248Z","updatedAt":
"2014-10-14T07:
16:
29.248Z","id":
"5436442ca1a14d1c60de3e16","username":
"apicloud","email":
"test@"}
验证Email
设置Email验证是APICloud云设置选项中的一项。
Email验证会在User对象中改变emailVerified字段的值，当一个用户的Email被新设置或者修改过的话，emailVerified会被设定为false。
APICloud会对用户填写的邮箱发送一个链接，当用户点击这个链接时，可以把emailVerified设置为true。
emailVerified字段有三种状态：
·true:
用户点击email中的地址来连接APICloud来验证Email地址。
邮箱验证通过后，emailVerified为true。
·false:
User对象最后一次被刷新的时候，用户并没有确认过他的Email地址，如果您看到emailVerified为false的话，您可以考虑刷新User对象。
·null:
所创建User对象未输入email。
请求验证Email
发送给用户的邮箱验证邮件在两周内失效，为了发送验证请求，需要向verifyEmail路径发送一个POST请求，示例如下：
curl-XPOST\-H"X-APICloud-AppId:
{{your_app_id}}"\-H"X-APICloud-AppKey:
{{your_app_key}}"\-H"Content-Type:
application/json"\-d'{"username":
"apicloud","email":
"customer@"}'\
无论发送邮件成功或失败，返回的主体都是JSON对象，成功返回：
{"status":
1,"msg":
"发送验证邮件成功"}
否则，如果失败，将返回包含具体错误原因信息的JSON对象：
{"status":
0,"code":
119,"msg":
"请在设置中开启邮箱验证服务"}
注意：
在进行邮件发送前，请先确认已经设置了云设置中的“注册用户邮箱验证”状态为开启状态。
密码重置
您可以使用这项功能，前提是用户将Email与他们的账户关联起来。
如果执行重置密码操作，需要发送一个POST请求到/resetRequest，示例如下：
curl-XPOST\-H"X-APICloud-AppId:
{{your_app_id}}"\-H"X-APICloud-AppKey:
{{your_app_key}}"\-H"Content-Type:
application/json"\-d'{"username":
"apicloud","email":
"test@"}'\
如果发送成功，返回的主体是一个JSON对象：
{"msg":
"请到邮箱查收邮件"}
获取用户
您可以发送一个GET请求到URL以获取用户信息，示例如下:
curl-XGET\-H"X-APICloud-AppId:
{{your_app_id}}"\-H"X-APICloud-AppKey:
{{your_app_key}}"\-H"Content-Type:
application/json"\
返回的body是一个JSON对象，包含所有用户提供的字段，除了密码以外，也包括了createdAt、updatedAt和objectId字段。
{"createdAt":
"2014-10-14T07:
16:
29.248Z","updatedAt":
"2014-10-14T07:
25:
52.026Z","id":
"5437a1a9e41cbf4a52d7c9d6","username":
"apicloud","email":
"test@","emailVerified":
null,"verificationToken":
"701fc3d75900a0307f30e084e8b24136f9784b05f8f21ed23b472453912e9604ee8561d3d10167cb10d36f3ea9c1b5c01cc2d43242ace893ab5902637e45d6e9"}
注意：
在进行用户获取操作后，相关系统会返回一个verificationToken（类似于userToken），相关Token时效为15分钟。
更新用户
为了更改一个用户已有的信息，需要对这个用户的URL发送一个PUT请求。
任何您没有指定过的key会保持不动，所以您可以只改动用户数据中的一部分，username和password均可以改动，您可以发送一个PUT请求到URL以更改用户信息，示例如下：
如果我们想对用户居住地址的信息做出一些修改:
curl-XPUT\-H"X-APICloud-AppId:
{{your_app_id}}"\-H"X-APICloud-AppKey:
{{your_app_key}}"\-H"Content-Type:
application/json"\-d'{"address":
"No.10,Building3,Haiweiroad,Haidiandistrict"}'\
如果成功，返回的body是一个JSON对象：
{"createdAt":
"2014-10-14T07:
16:
29.248Z","updatedAt":
"2014-10-14T07:
52:
34.055Z","id":
"543ccdcd6c0a61303282414e","username":
"apicloud","email":
"test@","emailVerified":
null,"verificationToken":
"701fc3d75900a0307f30e084e8b24136f9784b05f8f21ed23b472453912e9604ee8561d3d10167cb10d36f3ea9c1b5c01cc2d43242ace893ab5902637e45d6e9","address":
"No.10,Building3,Haiweiroad,Haidiandistrict"}
删除用户
为了在APICloud上删除一个用户，可以向它的URL上发送一个DELETE请求，示例如下：
curl-XDELETE\-H"X-APICloud-AppId:
{{your_app_id}}"\-H"X-APICloud-AppKey:
{{your_app_key}}"\-H"Content-Type:
application/json"\
角色
当您的app的规模和用户基数成长时，您可能发现您需要比ACL模型（针对每个用户）更加粗粒度的访问控制您的数据的方法。
为了适应这种需求,APICloud支持一种基于角色的权限控制方式。
角色系统提供一种逻辑方法让您通过权限的方式来访问您的APICloud数据。
角色是一种有名称的对象，包含了用户和其他角色。
任何授予一个角色的权限隐含着授予它包含着的其他的角色相应的权限。
创建角色
创建一个新角色，需要发送一个POST请求到role根路径，相关示例如下：
curl-XPOST\-H"X-APICloud-AppId:
{{your_app_id}}"\-H"X-APICloud-AppKey:
{{your_app_key}}"\-H"Content-Type:
application/json"\-d'{"name":
"manager1","description":
"managerdesc"}'\
如果创建成功，返回的body是一个JSON对象，除了包括角色名称外也包括了createdAt、updatedAt和objectId字段，相关JSON返回对象如下：
{"createdAt":
"2014-10-16T02:
31:
42.399Z","updatedAt":
"2014-10-16T02:
31:
42.399Z","id":
"543f2e0e474f229d61185565","name":
"manager","description":
"managerdesc"}
获取角色
您可以同样通过发送一个GET请求来获取某个角色对象。
例如我们想要获取上面创建的对象：
curl-XGET\-H"X-APICloud-AppId:
{{your_app_id}}"\-H"X-APICloud-AppKey:
{{your_app_key}}"\
https:
/
升级会员 