APICloud数据云API文档.docx

1、APICloud数据云API文档REST API 详解Restful API可以让您用任何可以发送 http 请求的设备来与 API Cloud 进行交互, 您可以使用 Restful API 做以下事情, 例如: 一个移动网站可以通过 Javascript 来获取 API Cloud 上的数据. 一个网站可以展示来自 API Cloud 的数据。 您可以上传大量的数据, 之后可以被一个移动 app 读取。 使用任何语言写的程序都可以操作 API Cloud 上的数据。 如果您不再需要使用 API Cloud，您可以导出您所有的数据。API 版本 1.0 版本：2014年9月15日发布。快速参

2、考所有的API访问都是通过HTTP进行的。相关API访问需要在下。对象URLHTTP功能/mcm/api/POST创建对象/mcm/api/GET获取对象/mcm/api/PUT更新对象/mcm/api/GET查询对象/mcm/api/DELETE删除对象用户URLHTTP功能/mcm/api/user/POST新增用户/mcm/api/user/loginGET登录/mcm/api/user/logoutGET登出/mcm/api/user/verifyEmailPOST发送验证邮件/mcm/api/user/resetRequestPOST密码重置/mcm/api/user/GET获取用户

3、/mcm/api/user/PUT更改用户信息/mcm/api/user/DELETE删除用户角色URLHTTP功能/mcm/api/rolePOST创建角色/mcm/api/role/GET获取角色/mcm/api/role/PUT更新角色/mcm/api/role/DELETE删除角色请求验证当调用 APICloud 云开发接口时，我们需要对头部信息中X-APICloud-AppKey 进行验证，X-APICloud-AppKey 的生成规则如下：your app key = SHA1（你的应用ID + UZ + 你的应用KEY +UZ + 当前时间毫秒数）.当前时间毫秒数例如：你的应用I

4、D是A6968565094002，而你的应用KEY是62FB16B2-0ED6-B460-1F60-EB61954C823B，则你在请求头部信息X-APICloud-AppKey中设置的值应为 A6968565094002+UZ+62FB16B2-0ED6-B460-1F60-EB61954C823B+UZ+当前时间毫秒数组合字符串后通过SHA1加密后返回的字符串.当前时间毫秒数。示例代码如下：var now = Date.now();var appKey = sha1(“A6968565094002+”UZ”+” 62FB16B2-0ED6-B460-1F60-EB61954C823B”+U

5、Z+now)+”.”+now请求格式对于POST和PUT请求，请求的主体必须是 JSON 格式，而且 HTTP header 的 Content-Type 需要设置为 application/json。 用户验证是通过 HTTP header 来进行的。X-APICloud-AppId头标明正在运行的是哪个App程序，而X-APICloud-AppKey头用来授权鉴定终端。 对于 Javascript 使用，API Cloud 支持跨域资源共享，所以您可以将这些 header 同 XMLHttpRequest 一同使用。响应格式对于所有的请求的响应格式都是一个 JSON 对象。 一个请求是否成

6、功是由 HTTP 状态码标明的。一个 2XX 的状态码表示成功，而一个 4XX 表示请求失败。当一个请求失败时响应的主体仍然是一个 JSON 对象，但是总是会包含 code。 您可以用它们来进行调试。对象对象格式通过 REST API 保存数据需要将对象的数据通过 JSON 来编码。 这个数据是无模式化的（Schema Free），这意味着您不需要提前标注每个对象上有那些 key。您只需要随意设置 key-value 对就可以， 后端会存储它的。举个例子，假设您准备设置一个公司信息。一个简单的对象可能包含： name: API Cloud, level: Branch, area: Haidi

7、an DistrictKey 必须是字母和数字组成的 String，Value 可以是任何可以 JSON 编码的东西。每个对象都有一个类名，您可以通过类名来区分不同的数据。例如, 我们可以把公司对象称之为 Company。我们推荐您使用 NameYourClassesLikeThis 和 nameYourKeysLikeThis 这样的格式为您的 Key-Value 命名，可以使您的代码看起来很漂亮。当您从 API Cloud 中获取对象时，一些字段会被自动加上：createdAt，updatedAt 和 objectID。这些字段的名字是保留的，您不能自行设置它们。我们上面设置的对象在获取时

8、应该是下面的样子。 name: API Cloud, level: Branch, area: Haidian District， createAt: 2014-08-20T02:06:57.931Z, updateAt: 2014-08-20T02:06:57.931Z , objectId: 5436219ea1a14d1c60de3e05createdAt 和 updatedAt 都是 UTC 时间戳，以 ISO 8601 标准和毫秒级精度储存：YYYY-MM-DDTHH:MM:SS.MMMMZ。objectId 是一个 string，在类中唯一标明了一个对象。在 REST API 中

9、class 级的在一个资源上的操作只会根据类名来进行。例如，如果类名是 Company，那么 class 的 URL 就是http:/针对于一个特定的对象的操作可以通过组织一个 URL 来做。例如， 对 Company 中的一个 objectId 为 5436219ea1a14d1c60de3e05 的对象的操作应使用如下 URL：创建对象为了在 API Cloud 上创建一个新的对象，应该向 class 的 URL 发送一个 POST 请求，其中应该包含对象本身。例如，要创建如上对象：curl -X POST -H X-APICloud-AppId: your_app_id -H X-API

10、Cloud-AppKey: your_app_key -H Content-Type: application/json -d name: API Cloud,level: Branch,area: Haidian District 当创建成功时，HTTP的返回Code是 200，响应的主体是一个 JSON 对象，包含新的对象的 objectId，createdAt和updateAt 时间戳。 id: 5436442ca1a14d1c60de3e06, name: API Cloud, level: Branch, area: Haidian District, createdAt: 2014

11、-10-09T08:15:40.843Z, updatedAt: 2014-10-09T08:15:40.843Z获取对象当你创建了一个对象时，你可以通过发送一个 GET 请求以获取它的内容。例如，为了得到我们上面创建的对象：curl -X GET -H X-APICloud-AppId: your_app_id -H X-APICloud-AppKey: your_app_key 返回的主体是一个 JSON 对象包含所有用户提供的字段加上 createdAt，updatedAt 和 objectId 字段： id: 5436442ca1a14d1c60de3e06, name: API Cl

12、oud, level: Branch, area: Haidian District, createdAt: 2014-10-09T08:15:40.843Z, updatedAt: 2014-10-09T08:15:40.843Z更改对象为了更改一个对象上已经有的数据，您可以发送一个 PUT 请求到对象相应的 URL 上，任何您未指定的 key 都不会更改，所以您可以只更新对象数据的一个子集。例如，我们来更改我们对象的一个 area 的字段：curl -X PUT -H X-APICloud-AppId: your_app_id -H X-APICloud-AppKey: your_app_

13、key -H Content-Type: application/json -d area:Dongcheng District 返回的主体是一个 JSON 对象包含所有用户提供的字段加上 createdAt，updatedAt 和 objectId 字段，其中 updatedAt 为最新的UTC更新时间戳。 id: 5436442ca1a14d1c60de3e06, name: API Cloud, level: Branch, area: Dongcheng District, createdAt: 2014-10-09T08:15:40.843Z, updatedAt: 2014-10-

14、09T08:34:28.153Z删除对象为了在 API Cloud 中删除一个对象，可以发送一个 DELETE 请求到指定的对象的 URL，比如：curl -X DELETE -H X-APICloud-AppId: your_app_id -H X-APICloud-AppKey: your_app_key 数据类型在API Cloud中创建对象时，相关对象字段数据类型可以被定义为以下十种的任何一种，相关支持数据类型如下： String Number Boolean Date File Array Object GeoPoint Pointer Relation用户新增用户注册一个新用户时

15、username 、password两个字段都是必要的。password 字段会以和其他的字段不一样的方式处理，它在储存时会被加密而且永远不会被返回给任何来自客户端的请求。 为了新增一个用户，需要向 user 路径发送一个 POST 请求，示例如下:curl -X POST -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 如果创建成功，返回的状态

16、码是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验证是API Cloud云设置选项中的一项。Email 验证会在 User 对象中改变 emailVerified 字段的值， 当一个用户的 Email 被新设置或

17、者修改过的话，emailVerified 会被设定为 false。 API Cloud 会对用户填写的邮箱发送一个链接，当用户点击这个链接时，可以把 emailVerified 设置为 true。emailVerified 字段有三种状态： true : 用户点击 email 中的地址来连接API Cloud 来验证Email地址。邮箱验证通过后，emailVerified 为 true。 false : User 对象最后一次被刷新的时候，用户并没有确认过他的 Email 地址，如果您看到 emailVerified 为 false 的话，您可以考虑刷新 User 对象。 null : 所创

18、建User 对象未输入email。请求验证Email发送给用户的邮箱验证邮件在两周内失效，为了发送验证请求，需要向verifyEmail路径发送一个 POST 请求，示例如下：curl -X POST -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: 发送验证邮件成功否则，如果

19、失败，将返回包含具体错误原因信息的JSON对象： status: 0, code: 119, msg: 请在设置中开启邮箱验证服务注意：在进行邮件发送前，请先确认已经设置了云设置中的“注册用户邮箱验证”状态为开启状态。密码重置您可以使用这项功能，前提是用户将 Email 与他们的账户关联起来。如果执行重置密码操作，需要发送一个 POST 请求到 /resetRequest，示例如下：curl -X POST -H X-APICloud-AppId: your_app_id -H X-APICloud-AppKey: your_app_key -H Content-Type: applicati

20、on/json -d username:apicloud,email:test 如果发送成功，返回的主体是一个 JSON 对象： msg: 请到邮箱查收邮件获取用户您可以发送一个 GET 请求到 URL 以获取用户信息，示例如下:curl -X GET -H X-APICloud-AppId: your_app_id -H X-APICloud-AppKey: your_app_key -H Content-Type: application/json 返回的 body 是一个 JSON 对象，包含所有用户提供的字段，除了密码以外，也包括了 createdAt、updatedAt 和 obje

21、ctId 字段。 createdAt: 2014-10-14T07:16:29.248Z, updatedAt: 2014-10-14T07:25:52.026Z, id: 5437a1a9e41cbf4a52d7c9d6, username: apicloud, email: test, emailVerified: null, verificationToken: 701fc3d75900a0307f30e084e8b24136f9784b05f8f21ed23b472453912e9604ee8561d3d10167cb10d36f3ea9c1b5c01cc2d43242ace893ab

22、5902637e45d6e9注意： 在进行用户获取操作后，相关系统会返回一个verificationToken（类似于userToken），相关Token时效为15分钟。更新用户为了更改一个用户已有的信息，需要对这个用户的 URL 发送一个 PUT 请求。 任何您没有指定过的 key 会保持不动，所以您可以只改动用户数据中的一部分，username 和 password 均可以改动，您可以发送一个 PUT 请求到 URL 以更改用户信息，示例如下：如果我们想对用户居住地址的信息做出一些修改:curl -X PUT -H X-APICloud-AppId: your_app_id -H X-AP

23、ICloud-AppKey: your_app_key -H Content-Type: application/json -d address:No.10, Building 3, Haiwei road, Haidian district 如果成功，返回的 body 是一个 JSON 对象： createdAt: 2014-10-14T07:16:29.248Z, updatedAt: 2014-10-14T07:52:34.055Z, id: 543ccdcd6c0a61303282414e, username: apicloud, email: test, emailVerified:

24、 null, verificationToken: 701fc3d75900a0307f30e084e8b24136f9784b05f8f21ed23b472453912e9604ee8561d3d10167cb10d36f3ea9c1b5c01cc2d43242ace893ab5902637e45d6e9, address: No.10, Building 3, Haiweiroad, Haidian district删除用户为了在 API Cloud 上删除一个用户，可以向它的 URL 上发送一个 DELETE 请求，示例如下：curl -X DELETE -H X-APICloud-Ap

25、pId: your_app_id -H X-APICloud-AppKey: your_app_key -H Content-Type: application/json 角色当您的 app 的规模和用户基数成长时，您可能发现您需要比 ACL 模型 (针对每个用户) 更加粗粒度的访问控制您的数据的方法。为了适应这种需求, API Cloud支持一种基于角色的权限控制方式。角色系统提供一种逻辑方法让您通过权限的方式来访问您的API Cloud 数据。角色是一种有名称的对象，包含了用户和其他角色。任何授予一个角色的权限隐含着授予它包含着的其他的角色相应的权限。创建角色创建一个新角色，需要发送一个

26、POST 请求到 role 根路径，相关示例如下：curl -X POST -H X-APICloud-AppId: your_app_id -H X-APICloud-AppKey: your_app_key -H Content-Type: application/json -d name:manager1,description:manager desc 如果创建成功，返回的 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: manager desc获取角色您可以同样通过发送一个 GET 请求来获取某个角色对象。例如我们想要获取上面创建的对象：curl -X GET -H X-APICloud-AppId: your_app_id -H X-APICloud-AppKey: your_app_key https:/