API Conventions

Below you will find descriptions of GlobalGiving API conventions.

RESTful

GlobalGiving API is based on a set of RESTful web-services through HTTPS which provides the simplest and quickest way to access information for GlobalGiving projects and to submit a donation. "REST" means that our API is resource-oriented. Calls are actually URLs that point to data you fetch or modify. In developing your application, our resources are generally the items you think of when you visit globalgiving.org - projects, photos, project summaries, and so forth. Therefore, if you want to fetch data about a project at GlobalGiving, you would make an HTTP GET request, accompanied by the proper URI for the project about which you want information.

Request and Response Mime Types

Request Formatting

There are two ways in which to pass parameters to the system: by posting valid XML or JSON. Setting the correct Content-Type header with either 'Content-Type: application/xml' for XML or 'Content-Type: application/json' for JSON notifies our system which mime type was used, allowing us to properly interpret the parameters. The following XML and JSON cURL requests are equivalent:

XML Request Example

                  curl -H "Accept: application/xml" -H "Content-Type: application/xml" -d 
                  "<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
                  <auth_request>
                    <user>
                      <email>John_Doe@hotmail.com</email>
                      <password>somepassword</password>
                    </user>
                    <api_key>eb52c848-8e67-461b-a45d-9c85d9004dd3</api_key>
                  </auth_request>" -X POST https://api.globalgiving.org/api/userservice/tokens
               

NOTE: Above XML request has carriage returns for readability.

JSON Request Example

            
                  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
               

Response Formatting

Like requests, changing the Accept header indicates what mime format you would like the results in. Responses may be formatted as XML 'Accept: application/xml' or JSON 'Accept: application/json'.

Here is a chart of the mime types for each of these formats:

NOTE: There is one exception for the Get Progress Report request. For this operation, the Accept header must be set to 'Accept: application/atom+xml' for an XML response as the format used is in the Atom standard.

Sample XML Response

                  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
                  <auth_response>
                      <access_token>sqbkktg3s00vzz7gg3s198rzb9g3s2me2u2ng3s3</access_token>
                  </auth_response>
               

Equivalent JSON Response

                  {"auth_response":{"access_token": "njd9wng4d0ycwnn3g4d1jm30yig4d27iom5lg4d3"}}
               

Error Responses

When an error is encountered the format returned is as follows:

                  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
                  <error_response>
                      <error_code>401</error_code>
                      <errors>
                          <error>
                              <error_number>1234</error_number>
                              <error_message>api_key [568d6546-fce4-4de5-8cd9-608f65d556e0] is not registered in the system.</error_message>
                          </error>
                     .
                     .  
                      </errors>
                      <status>Unauthorized</status>
                  </error_response>
               

NOTE: An <error_response> will always contain one or more <error> elements, contained with the <errors> element, with a corresponding <error_message> describing the problem. An optional <error_number> element may be present with error message with a numeric error number. This applies primarily for credit card donation errors and declined transactions, and these values can be seen in Paypal's PayflowPro Developers Guide (see Table 6.9). The values in The <error_code> and <status> elements will only appear once for every <error_response> message.

List of Return Codes and Statuses

All codes and statuses returned for a successful or error response follow the standard HTTP response status codes.