chrislovecnm/iGivefirst API Draft

## iGivefirst API Draft
#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"             : "bilbo.baggins@gmail.com",
        "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"             : "bilbo.baggins@gmail.com",
        "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
	#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" : "bilbo.baggins@gmail.com",
	"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" : "bilbo.baggins@gmail.com",
	"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