API Conventions

Below you will find descriptions of GlobalGiving API conventions.

RESTful

The 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:

	Content-Type Request	Accept Response
XML	application/xml	application/xml
JSON	application/json	application/json

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.

Code	Status	Defintion
200	OK	The request has succeeded.
400	Bad Request	The request could not be understood by the server due to malformed syntax or invalid values were provided. The client SHOULD NOT repeat the request without modifications.
401	Unauthorized	The request requires or failed user authentication.
404	Not Found	The server has not found anything matching the Request-URI.
410	Gone	The resource is intentionally unavailable. Used when a project has gone inactive.
500	Internal Server Error	The server encountered an unexpected condition which prevented it from fulfilling the request.
503	Service Unavailable	The server is currently unable to handle the request due to maintenance of the server. This is a temporary condition which will be alleviated after some delay.