API的约定

下面你将看到GlobalGiving API约定的描述。

宁静的

GlobalGiving API它基于一套通过HTTPS的RESTful网络服务，提供了最简单、最快的方式来访问GlobalGiving项目的信息和提交捐赠。“REST”意味着我们的API是面向资源的。调用实际上是指向您获取或修改的数据的url。在开发您的应用程序时，我们的资源通常是您访问globalgiving.org时想到的项目、照片、项目摘要等等。因此，如果您想从GlobalGiving获取关于一个项目的数据，您将发出一个HTTP GET请求，并附带您想要信息的项目的正确URI。

请求和响应Mime类型

请求格式

向系统传递参数有两种方法:发布有效的XML或JSON。设置正确的内容类型用任意一个标头“内容类型:应用程序/ xml”，或“application / json内容类型:for JSON通知我们的系统使用了哪种mime类型，允许我们正确地解释参数。以下XML和JSON cURL请求是等价的:

XML请求示例

Content-Type: application/xml" -d "   John_Doe@hotmail.com somepassword  eb52c848-8e67-461b-a45d-9c85d9004dd3 " -X POST https://api.globalgiving.org/api/userservice/tokens

注意:为了可读性，上面的XML请求有回车。

JSON请求示例

curl -H "Accept: application/xml" -H "Content-Type: application/json" -d "{'auth_request':{'user':{'email':'John_Doe@hotmail.com'， 'password':'somepassword'}， 'api_key':'eb52c848-8e67-461b-a45d-9c85d9004dd3'}}" -X POST https://api.globalgiving.org/api/userservice/tokens

响应格式

像请求，改变接受标头指示你想要什么样的mime格式的结果。响应可以格式化为XML“接受:application / xml”或JSON接受:application / json的．

下面是每种格式的mime类型的图表:

	内容类型的请求	接受响应
XML	应用程序/ xml	应用程序/ xml
JSON	application / json	application / json

注意:Get Progress Report请求有一个例外。对于此操作，接受头必须设置为“接受:application / atom + xml”作为Atom标准中使用的格式的XML响应。

XML响应示例

<？xml版本="1.0" encoding="UTF-8" standalone="yes"?>  sqbkktg3s00vzz7gg3s198rzb9g3s2me2u2ng3s3

等价的JSON响应

{" auth_response ":{“access_token”:“njd9wng4d0ycwnn3g4d1jm30yig4d27iom5lg4d3}}

错误响应

当遇到错误时，返回的格式如下:

<？xml版本="1.0" encoding="UTF-8" standalone="yes"?>  401   1234 api_key [568d6546-fce4-4de5-8cd9-608f65d556e0]未在系统中注册。  . . Unauthorized  .  Unauthorized

注意:一个< error_response >是否总是包含一个或多个< >错误元素，包含在< >错误元素，用对应的< error_message >描述问题。一个可选的< error_number >元素可能显示带有数字错误号的错误消息。这主要适用于信用卡捐赠错误和拒绝交易，这些价值可以在贝宝的PayflowPro开发者指南(见表6.9)。中的值< error_code >而且< >状态元素只会出现一次< error_response >消息。

返回代码和状态列表

成功或错误响应返回的所有代码和状态都遵循标准HTTP响应状态代码。

代码	状态	的定义
200	好吧	请求成功。
400	坏的请求	由于语法错误或提供了无效值，服务器无法理解请求。客户不应该重复没有修改的请求。
401	未经授权的	请求需要或失败的用户身份验证。
404	没有找到	服务器没有找到任何与Request-URI匹配的内容。
410	走了	资源故意不可用。在项目已变为非活动状态时使用。
500	服务器内部错误	服务器遇到了一个意外的情况，阻止了它完成请求。
503	服务不可用	由于服务器的维护，服务器当前无法处理请求。这是一个暂时的情况，经过一段时间的拖延后会得到缓解。