Our API
Another Way To Connect With GlobalMojo
Welcome to the GlobalMojo API!
Our API will allow you to connect with our application and provide basic Giving Assistant features to your users. This quick guide will cover the basics, from authentication to registering a user and obtaining a URL to download the Giving Assistant.
API Access
To request access to our system via the API, please fill out the contact form here. We will provide you with the necessary keys so that you can start submitting requests. Additionally, some partners like to provide a better experience to their users by offering a Giving Assistant that has been branded for their campaign. We are happy to accommodate your needs! Contact us for more information and to request API access.
A RESTful API
Our API provides a REST interface to our system, accessed via HTTP. We accept and return data in JSON format where noted. For more gory details on what this means, please visit the following helpful links:
http://en.wikipedia.org/wiki/RESTful#RESTful_web_services
http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol
http://en.wikipedia.org/wiki/JSON
Application Flow
A successful API session typically comes in two flavors that look like this:
- Register a user
- Download the product
OR
- Get general information about a user
- Get statistical information about a user
Authentication
We utilize OAuth 1.0. OAuth is an open protocol to allow secure API authorization in a simple and standard method from desktop and web applications. For more information about the nitty-gritty details of OAuth, visit http://oauth.net/
When we setup your API access, we will provide you with your OAuth key and secret.
Additionally, you might be interested in knowing that we have selected "HMAC-SHA1" as our signing method and that we are utilizing a 2-legged scheme (no need for tokens).
Response Data
We will return data to you in either XML or JSON formats. You can select which format you prefer by specifying an "Accept" header with the appropriate MIME type ("application/json", "application/xml", "text/json", "text/xml"). The default is to return JSON, as displayed in the examples below.
Working with Users
Overview
Endpoint: http://api.globalmojo.com/api/user
| Method | Description | Takes | Returns |
|---|---|---|---|
| GET | Retrieve details about an existing user. | User token | User data, see example |
| POST | Create a new user | User data, see example | |
| PUT | Update an existing user's information | User token | |
| DELETE | Flag an existing user as inactive | User token |
Example
Request
GET http://api.globalmojo.com/api/user/EkPEBpqta36zYxpYaYjfIxRT97OH3mB6x6pVPqCw2J54xJdRGooDTz6B9eK5ccQY
Authorization: OAuth realm="",oauth_version="1.0" ,oauth_consumer_key="1fed64aa6c69847d78a9cca03375e9ebf034d881", oauth_timestamp="1332217254",oauth_nonce="42ODkqueTcP", oauth_signature_method="HMAC-SHA1", oauth_signature="mXbCfCC9G0gsDLNsljuRZFu1V54%3D"
Response
{"gm_status_code":1,"gm_status_message":"Request was Successful","data":{"userid":"12345","firstname":"Test","lastname":"User","email":"test@testuser.com","auth_type":"gm","toolbartoken":"EkPEBpqta36zYxpYaYjfIxRT97OH3mB6x6pVPqCw2J54xJdRGooDTz6B9eK5ccQY","username":"testuser","refercode":"4HfKGUxOnlY9p3ghkJsN","fbId":"123456789"},"request_method":"GET"}
Grabbing Dashboard Details
Overview
Endpoint: http://api.globalmojo.com/api/dashboard
| Method | Description | Takes | Returns |
|---|---|---|---|
| GET | Retrieve dashboard details about a user and their cause. | User token | Dashboard data, see example |
Example
Request
GET http://api.globalmojo.com/api/dashboard/EkPEBpqta36zYxpYaYjfIxRT97OH3mB6x6pVPqCw2J54xJdRGooDTz6B9eK5ccQY
Authorization: OAuth realm="",oauth_version="1.0" ,oauth_consumer_key="1fed64aa6c69847d78a9cca03375e9ebf034d881", oauth_timestamp="1332217254",oauth_nonce="42ODkqueTcP", oauth_signature_method="HMAC-SHA1", oauth_signature="mXbCfCC9G0gsDLNsljuRZFu1V54%3D"
Response
{"gm_status_code":1,"gm_status_message":"Request was Successful","data":{"dollars":"$3.10","modough":0,"mojo":510,"entries":510,"monthlyentries":510,"contributions":"$3.10","overall_ranking_string":"301st","overall_ranking_numeral":"301","invites":1,"campaign_revenue":"$15,665.00"},"request_method":"GET"}
Downloading the Giving Assistant
Overview
Endpoint: http://api.globalmojo.com/api/download
| Method | Description | Takes | Returns |
|---|---|---|---|
| GET | Retrieve the URL and Just In Time HTML | Browser type (googlechrome, firefox, microsoftie, applesafari) | URL and HTML |
Example
Request
GET http://api.globalmojo.com/api/downloadurl/googlechrome
Authorization: OAuth realm="",oauth_version="1.0" ,oauth_consumer_key="1fed64aa6c69847d78a9cca03375e9ebf034d881", oauth_timestamp="1332217254",oauth_nonce="42ODkqueTcP", oauth_signature_method="HMAC-SHA1", oauth_signature="mXbCfCC9G0gsDLNsljuRZFu1V54%3D"
Response
{"gm_status_code": 1,"gm_status_message": "Request was Successful","data": {"downloadlink": "http://cdn.globalmojo.com/extension/GivingAssistant-3.1.0-21.crx","instructions": "<<<<HTML CODE HERE REMOVED FOR SIMPLICITY>>>>","download_btn": "<<<<HTML CODE HERE REMOVED FOR SIMPLICITY>>>>","download_txt": "FREE DOWNLOAD"},"request_method": "GET"}
Error Codes and Responses
| Code | Meaning |
|---|---|
| 1 | Request was successful |
| 2 | No such resource available |
| 3 | Bad parameters passed |
| 4 | Bad OAuth Request: Check your signtures and parameters |
| 5 | Method not allowed for this resource |
| 6 | Invalid operation |
| 7 | Unable to locate the requested resource |
| 9 | The oauth_nonce value was used in a previous request |
| 10 | The oauth_timestamp value was not accepted, maybe its expired |
| 11 | The oauth_consumer_key is temporarily unacceptable |
| 12 | The consumer key was refused |
| 13 | The oauth_signature is invalid |
| 14 | The oauth_token has been consumed |
| 15 | The oauth_token has expired |
| 16 | The oauth_token has been revoked |
| 17 | The oauth_token was not accepted |
| 18 | oauth_verifier is incorrect |
| 19 | The oauth_signature_method was not accepted |
| 20 | A required OAuth parameter was not received |
| 21 | Unable to locate the requested resource |
| 23 | The Facebook record is already registered |
