Created
March 13, 2013 15:38
-
-
Save chrislovecnm/5153326 to your computer and use it in GitHub Desktop.
iGivefirst API Draft
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
#iGivefirst API | |
This api allows iGivefirst partners to show nonprofit advertisements on their websites and collect donations on behalf of iGivefirst, and nonprofits. | |
## General Concepts | |
### Guids | |
Our API utizes business keys in the form of standard 36 character guids. These guids are created with-in our system and are unique. The main guids that are utilized: | |
- Nonprofit Campaign Guid - This is the guid representation of a campaign setup by a nonprofit. This guid is accessible through the ad serving api, and is used by virtually all api calls. | |
- Publisher Campaign Guid - This is the guid that is created when a publisher campaign is created. Again this guid is used with virtually every call. | |
- Publisher Account Guid - In order to call our API to process donations an publisher account guid is utilized. TODO where do you get this | |
## Nonprofit Ad Serving | |
Nonprofit Ad Serving provides a iGivefirst partner with the capability to serve nonprofit ads on their websites. You are able to configure the types of ads through our publisher web based interface. This service delivers JSON out via JSON or JSONP Ajax calls. If the publisher campaign guid is incorrect we serve a default ad serve. The point of this call is to always get a json object for ad serving. | |
- URI: /nonprofit-json/qqrda85324-a379-40af-aa13-aec414c6e3b1 | |
- base url is /nonprofit-json/ with the publisher campaign guid | |
- HTTP Method: GET | |
- HTTP Codes | |
- - 200 succesful api call | |
- 500 internal server error | |
### Example JSON Object | |
The following code block is an example of the JSON that is create by this service. The results are returned as an array of | |
```json | |
[{ | |
"guid" : "acda85324-a379-40af-aa13-aec414c6e3b1", | |
"nonProfitdescription" : "This is the description", | |
"adImage" : "https://www.cnmd.com/the_large_image.jpg", | |
"thumbImage" : "https://www.cdn.com/this_is_ad_small_image.jpg", | |
"nonProfitwebsiteUrl" : "http://www.redcross.com", | |
"nonProfitname" : "American Red Cross", | |
"subNonprofitName" : "Red Cross", | |
"nonProfitguid" : "fc1d6a1b-fc7f-401a-8488-c76080caac4c", | |
"reliefTypes" : ["People Disaster Relief"], | |
"city" : "Denver", | |
"state" : "Colorado", | |
"ein" : "1246578" | |
}, | |
{ | |
"adImage": "https://a924a4ac4c54f72ed72d-9d1004d793edd85be00660d315adbbd2.ssl.cf2.rackcdn.com/Operation-Homefront-Inc-a5fb4301-5589-4b99-af24-2cd02f3820be.jpeg", | |
"thumbImage": "https://a924a4ac4c54f72ed72d-9d1004d793edd85be00660d315adbbd2.ssl.cf2.rackcdn.com/Operation-Homefront-Inc-a5fb4301-5589-4b99-af24-2cd02f3820be-thumb.jpeg", | |
"tags": false, | |
"guid": "a5fb4301-5589-4b99-af24-2cd02f3820be", | |
"nonProfitwebsiteUrl": "http://www.operationhomefront.net", | |
"nonProfitname": "Operation Homefront Inc", | |
"nonProfitguid": "119a8ee7-8d5e-4b57-8212-7f25eabbf82c", | |
"nonProfitdescription": "We care for military families while the service members are at war, providing rent, utilities, and food assistance.", | |
"city" : "Denver", | |
"state" : "Colorado", | |
"ein" : "1246578" | |
} | |
] | |
``` | |
## Secure Rest Donation API | |
The following API can be used by iGivefirst publishing partners to process a donation collected through a partners website | |
### Obtaining a private key | |
This process is currently in ALPHA. We will be releasing a user guid shorly | |
### Authenticating requests using Rest API | |
Authenticating Requests Using the REST API | |
When accessing iGivefirst API using REST , you must provide the following items in your request so the request can be authenticated: | |
#### Request Elements | |
* iGivefirst Access Key Id - It is the access key id of the identity you are using to send your request. | |
* Signature — Each request must contain a valid request signature, or the request is rejected. A request signature is calculated using your Secret Access Key, which is a shared secret known only to you and iGivefirst. | |
* Time stamp — Each request must contain the date and time the request was created, represented as a string in UTC. An example of the timestamp is: Thu, 18 Nov 2010 11:27:35 GMT. This timestamp must match the | |
accompanying HTTP Date Header | |
###### Authorization | |
The iGivefirst REST API uses the standard HTTPAuthorization header to pass authentication information. | |
The following is an example of the header: | |
* Authorization: IGF AKIAIOSFODNN7EXAMPLE:frJIUN8DYpKDtOLCwo//yllqDzg= | |
The header consists of the iGivefirst Access Key Id concatenated with the Signature. | |
* iGivefirst Access Key Id - IGF AKIAIOSFODNN7EXAMPLE: | |
* Signature - frJIUN8DYpKDtOLCwo//yllqDzg= | |
The Signature is comprise of Base64( HMAC-SHA1( YourSecretAccessKeyID, UTF-8-Encoding-Of( StringToSign ) ) ); | |
StringToSign = | |
HTTPVerb +"\n" | |
MD5-HASH-OF-Content + "\n" + | |
Content-Type + "\n" + | |
Timestamp + "\n" + | |
CanonicalizedResourceURI | |
An Example of the StringToSign | |
``` | |
POST\n | |
bc1153d10db6079ecfbe3c3dca023402\n | |
application/json\n | |
Thu, 15 Sep 2012 00:51:48 GMT\n | |
/igive-api/v1/donation | |
``` | |
or | |
``` | |
GET\n | |
\n | |
\n | |
Thu, 15 Sep 2012 00:51:48 GMT\n | |
/igive-api/v1/donation/5def4c5f-e318-471f-9ef7-05cc965233cd | |
``` | |
or | |
``` | |
DELETE\n | |
\n | |
\n | |
Thu, 15 Sep 2012 00:51:48 GMT\n | |
/igive-api/v1/donation/5def4c5f-e318-471f-9ef7-05cc965233cd | |
``` | |
The StringToSign is then used to build the Signature by | |
1. UTF-8 Encoding the StringToSign | |
2. Used as a parameter creating a HMAC-SHA1, where your secret access key is the key | |
3. Lastly Base64 Encoded | |
Once you have your Signature you create the Authorization header by contenating your Access Key and the Signature: | |
Authorization: IGF AKIAIOSFODNN7EXAMPLE:frJIUN8DYpKDtOLCwo//yllqDzg= | |
#### White Listed IP Addresses | |
The production system only communicates to the IP addresses that you have listed during the setup of the donation key. | |
### Donation API Endpoint | |
The donation api is used to create, get or delete a donation. | |
#### Headers Used | |
* Content Type: application/json | |
* Accepts: application/json (where applicable) | |
* Date: Thu, 15 Sep 2012 00:51:48 GMT | |
* Authorization: IGF AKIAIOSFODNN7EXAMPLE:frJIUN8DYpKDtOLCwo//yllqDzg= | |
#### HTTP Verbs | |
##### GET - Get a donation | |
* URI - /igive-api/v1_0/donation/{guid-of-donation} | |
* RETURNS - full json donation object which includes optional fields such as nonprofit name | |
* SUCCESS CODE - 200 | |
* ERROR CODES - TODO | |
Example | |
``` | |
GET /igive-api/v1_0/donation/59e680df-df0a-42c3-969a-800d35ca5684 | |
Accepts: application/json | |
Date: Tue, 27 Mar 2007 21:15:45 +0000 | |
Authorization: IGF AKIAIOSFODNN7EXAMPLE:frJIUN8DYpKDtOLCwo//yllqDzg= | |
``` | |
Response | |
```json | |
{ | |
"guid" : "59e680df-df0a-42c3-969a-800d35ca5684", | |
"amount" : 42.80, | |
"sponsorMatchingPercentage" : 20, //optional | |
"nonProfitCampaignGuid" : "8aec529c-dc93-4e5a-a02d-2965f16d327e", | |
"publisherCampaignGuid" : "59e680df-df0a-42c3-969a-800d35ca5684", | |
"sponsorCampaignGuid" : "ca712410-8e11-46a5-872c-de8ba7744e42", // optional | |
"publisherTransactionId" : "42", // optional provided by publisher | |
"publisherAccountGuid" : "ca712410-8e11-46a5-872c-de8ba7744e42", | |
"donor" : { | |
"publisherDonorId" : "42", // optional - supplied by the publisher | |
"firstName" : "Frodo", | |
"lastName" : "Baggins", | |
"sharePersonalInfo" : false, | |
"billingAddress1" : "123 Shire Blvd", | |
"billingAddress2" : "Lower Hobbit Hole", // optional | |
"billingCity" : "Denver", | |
"billingState" : "CO", // optional | |
"billingZip" : "80125", // optional | |
"billingCountry" : "US", // ISO 2 digit country code | |
"email" : "[email protected]", | |
"cellPhoneNumber" : "3035511234", // optional | |
"workPhoneNumber" : "234134435", // optional | |
"homePhoneNumber" : "1213" //optional | |
}, | |
"status" : "NON_PROFIT_PAID", // various status codes - PENDING_BATCH, PUBLISHER_BATCH_COMPLETED, PUBLISHER_PAYMENT_ERROR, NONPROFIT_PAID, NONPROFIT_PAYMENT_ERROR, ON_HOLD, CANCELLED, EXCEPTION | |
"dateCreated" : "2013-02-14:14:23:00Z", // ISO 3602 timestamp YYYY-MM-DDThh:mmZ GMT | |
"publiserName": : "Publisher Name", | |
"nonProfitName": : "Hobbit's for Humanity", | |
"sponsorName" : : "Thorin & Co." // optional | |
} | |
``` | |
##### POST - Create a donation | |
* URI: /igive-api/v1_0/donation | |
* BODY - donation object | |
* SUCCESS CODE - 201 created | |
* ERROR CODES | |
- 500 internal error | |
- 400 malformed post body | |
- 401 unauthorized (may not be thrown) | |
Example | |
``` | |
POST /igive-api/v1_0/donation | |
Accepts: application/json | |
Content-Type: application/json | |
Date: Tue, 27 Mar 2007 21:15:45 +0000 | |
Authorization: IGF AKIAIOSFODNN7EXAMPLE:frJIUN8DYpKDtOLCwo//yllqDzg= | |
``` | |
Body | |
```json | |
{ | |
"amount" : 42.80, // amount in USD | |
"sponsorMatchingPercentage" : 20, // optional | |
"nonProfitCampaignGuid" : "8aec529c-dc93-4e5a-a02d-2965f16d327e", | |
"publisherCampaignGuid" : "59e680df-df0a-42c3-969a-800d35ca5684", | |
"sponsorCampaignGuid" : "ca712410-8e11-46a5-872c-de8ba7744e42", // optional | |
"publisherTransactionId" : "42", // optional - supplied by the publisher | |
"publisherAccountGuid" : "ca712410-8e11-46a5-872c-de8ba7744e42", | |
"donor" : { | |
"publisherDonorId" : "42", // optional - supplied by the publisher | |
"firstName" : "Frodo", | |
"lastName" : "Baggins", | |
"sharePersonalInfo" : false, | |
"billingAddress1" : "123 Shire Blvd", | |
"billingAddress2" : "Lower Hobbit Hole", | |
"billingCity" : "Denver", | |
"billingState" : "CO", | |
"billingZip" : "80125", | |
"billingCountry" : "US", | |
"email" : "[email protected]", | |
"cellPhoneNumber" : "3035511234", | |
"workPhoneNumber" : "234134435", | |
"homePhoneNumber" : "1213" | |
} | |
} | |
``` | |
Response Success | |
```json | |
{ | |
"guid" : "8aec529c-dc93-4e5a-a02d-2965f16d327e" | |
} | |
``` | |
Response Failure | |
```json | |
{ | |
"errors" : ["Error message1", "Error message 2"] // human readable error messages | |
} | |
``` | |
##### DELETE - Cancel a donation | |
* URI: /igive-api/v1_0/donation/{guid-of-donation} | |
* RETURNS - string that is the guid for the donation | |
* SUCCESS CODE - 201 | |
* ERROR CODES | |
- 500 internal error | |
- 401 unauthorized (may not be thrown) | |
Example | |
``` | |
DELETE /igive-api/v1_0/donation/59e680df-df0a-42c3-969a-800d35ca5684 | |
Date: Tue, 27 Mar 2007 21:15:45 +0000 | |
Authorization: IGF AKIAIOSFODNN7EXAMPLE:frJIUN8DYpKDtOLCwo//yllqDzg= | |
``` | |
##### PUT - not implemented | |
Cancel the donation with DELETE and then POST to create new donation | |
* ERROR CODES - 405 - method not allowed |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment