Objects:

·     SavingGoal: Represents and tracks each item a user is saving up for

·     PaymentProvider: Information about the service (Paypal, Amazon, Google) that will be used and the users credentials for that service

·     Contribution: Tracks who has submitted towards a goal, and how much

DTD:

<?xml version="1.0"?>

<!ELEMENT Savings (SavingGoal*)>

<!ELEMENT SavingGoal (Id, ExternalItemId, Name, StartingAmount, GoalAmount, CurrentAmount, EndDate, Contributions, PaymentProviders, ConfirmationURL,      CancelURL, RecordVersionNumber, RecordOwner)>

<!ELEMENT Contributions (Contribution*)>

<!ELEMENT Contribution (Id, Amount, Date, Contributor, Message, Status, ProviderName, ProviderURL)>

<!ELEMENT Id (#ID)>

<!ELEMENT Email (#PCDATA)>

<!-- Used for optomistic locking -->

<!ELEMENT RecordVersionNumber (#PCDATA)>

<!ELEMENT ExternalItemId (#ID)>

<!ELEMENT Name (#CDATA)>

<!ELEMENT StartingAmount (#PCDATA)>

<!ELEMENT GoalAmount (#PCDATA)>

<!ELEMENT CurrentAmount (#PCDATA)>

<!ELEMENT EndDate (#PCDATA)>

<!ELEMENT Amount (#PCDATA)>

<!ELEMENT Date (#PCDATA)>

<!ELEMENT Contributor (#CDATA)>

<!ELEMENT Message (#CDATA)>

<!-- his list will change as I learn more about the providers apis -->

<!ELEMENT Status (Submitted|Pending|Authorized|Settled|Failed|Canceled)>

<!-- This is filled in by the contributions service and it contains the URL to redirect the user to -->

<!ELEMENT ProviderURL (#PCDATA)>

<!-- This is the url for the clients confirmation page -->

<!ELEMENT ConfirmationURL (#PCDATA)>

<!-- This is the url when the customer decides to cancel on the providers site -->

<!ELEMENT CancelURL (#PCDATA)>

<!ELEMENT PaymentProviders (PaymentProvider+)>

<!ELEMENT PaymentProvider (ProviderName, Credentials)>

<!ELEMENT ProviderName (PayPal|Amazon|Google)>

<!-- I'm assuming the credentials will be different by provide.  e.g just email for paypal -->

<!ELEMENT Credentials (#CDATA)>

 

Sample XML

<Savings>

  <SavingGoal>

    <Id>1</Id>

    <ExternalItemId>12345</ExternalItemId>

    <Name>Porsche 911</Name>

    <StartingAmount>0.00</StartingAmount>

    <GoalAmount>100000.00</GoalAmount>

    <CurrentAmount>1.00</CurrentAmount>

    <EndDate>12/25/2008</EndDate>

    <PaymentProviders>

      <PaymentProvider>

        <ProviderName>Paypal</ProviderName>

        <Credentials>rob@larubbio.org </Credentials>

      </PaymentProvider>

    </PaymentProviders>

    <Contributions>

      <Contribution>

        <Id>1</Id>

        <Amount>1.00</Amount>

        <Date>5/28/2008</Date>

        <Contributor>Mom</Contributor>

        <Message>Happy Birthday!  Good luck saving up for the Porsche</Message>

        <Status>SETTLED</Status>

        <ProviderName>PayPal</ProviderName>

        <ProviderURL>{Payment Provider specific payment URL}</ProviderURL>

        <RecordVersionNumber>1</RecordVersionNumber>

      </Contribution>

    </Contributions>

    <ConfirmationURL>http://www.wishpot.com/contribution/confirm </ConfirmationURL>

    <CancelURL>http://www.wishpot.com/contribution/cancel</CancelURL>

    <RecordVersionNumber>1</RecordVersionNumber>

  </SavingGoal>

</Savings>

 

Notes:

·     Any externally presented Id's should not be monotonically increasing ints. This is to prevent id phishing and to stop information leakage about service adoption rates. (NOT IMPLEMENTED)

·     PaymentProvider credentials are sent to the service, but never returned to a client.

·     CRUD operations through the REST api are always restricted to records the client created. In the case where an operation is attempted against a record the client does not own a 403 Forbidden will be returned.

REST API:

 

    

 

Verb	URI	Query String	Request Body	Response Code	Response Body	Other Remarks
GET	/Savings	Id, ExternalItemId, ExternalItemIdSubstring	Ignored	200 OK, 400 Bad Request	SRX	Searches among saving goals based on the provided URL params.
PUT	/Savings	Ignored	Ignored	405 Method Not Allowed	Error	PUT not allowed on Savings URI
POST	/Savings	Ignored	SRX	201 Created, 400 Bad Request	SRX	New saving goal(s) will be created if data is sufficient in request SRX. 400 response if there is missing dat..
DELETE	/Savings	Id	Ignored	200 OK, 400 Bad Request, 404 Not Found	Empty	200 If id valid, else 404 if id invalid, 400 if no id param supplied
GET	/SavingGoal/{Id}	Ignored	Ignored	200 Ok, 404 Not Found, 403 Forbidden	SGRX	404 if id supplied is invalid
PUT	/SavingGoal/{Id}	Ignored	SGRX	200 Ok, 400 Bad Request, 404 Not Found, 403 Forbidden, 409 Conflict	SGRX	Will update the saving goal with supplied id. Returns 409 if the update is for an older version of the record
POST	/SavingGoal/{Id}	Ignored	Ignored	405 Method Not Allowed	Error	Post forbidden on this URI
DELETE	/SavingGoal/{Id}	Ignored	Ignored	200 Ok, 400 Bad Request, 404 Not Found, 403 Forbidden	Empty	Logically deletes the SavingGoal record. 404 if the id is invalid.
GET	/SavingGoal	Ignored	Ignored	400 Bad request	empty	GET must specify id in URI
PUT	/SavingGoal	Ignored	Ignored	400 Bad request	empty	PUT must specify id in URI
POST	/SavingGoal	Ignored	Ignored	400 Bad request	empty	POST forbidden on this URI
DELETE	/SavingGoal	Ignored	Ignored	400 Bad request	empty	DELETE must specify id in URI
GET	/SavingGoal/{id}/Contributions	Status, Id	Ignored	200 Ok, 404 Not Found, 403 Forbidden	CSRX	Either returns all the contributions for this saving goal, or just the ones matching status or id
PUT	/SavingGoal/{id}/Contributions	Ignored	Ignored	405 Method Not Allowed	Error	PUT forbidden on this URI
POST	/SavingGoal/{id}/Contributions	Ignored	CRX	200 Ok, 404 Not Found, 405 Not Allowed	CRX	Creates a new contribution in status 'Submitted'
DELETE	/SavingGoal/{id}/Contributions	Ignored	Ignored	405 Not Allowed	Error XML	DELETE forbidden on this URI
GET	/Contribution/{Id}	Ignored	Ignored	200 Ok, 404 Not Found, 405 Not Allowed	CRX
PUT	/Contribution/{Id}	Ignored	CRX	200 Ok, 400 Bad Request, 404 Not Found, 403 Forbidden, 409 Conflict	CRX	Will update the saving goal with supplied id. Returns 409 if the update is for an older version of the record
POST	/Contribution/{Id}	Ignored	Ignored	405 Not Allowed	Error	POST Forbidden on this URI
DELETE	/Contribution/{Id}	Ignored	Ignored	200 Ok, 400 Bad Request, 404 Not Found, 405 Not Allowed, 409 Conflict	CRX	Cancels the contribution associated with the Id. Contributions can only be canceled if the status is Submitted (Potentially contributiuons in Pending or Authorized may be canceled depending on provider api)

 

SGRX = Savings Goal Representation XML, SRX = Savings Representation XML, CSRX = Contributions Representation XML, CRX = Contribution Representation XML

 

Use Cases:

Creating a Saving Goal

Client:

POST http://www.wishpot.com/api/savings?ApiKey={RecordOwner} HTTP/1.1

 

<SavingGoal>

  <ExternamItemId>12345</ExternalItemId>

  <Name>Porsche 911</Name>

  <StartingAmount>0.00</StartingAmount>

  <GoalAmount>100000.00</GoalAmount>

  <EndDate>12/25/2008</EndDate>

  <PaymentProviders>

    <PaymentProvider>

      <ProviderName>Paypal</ProviderName>

      <Credentials>rob@larubbio.org</Credentials>

    </PaymentProvider>

  </PaymentProviders>

</SavingGoal>

Server response:

HTTP/1.1 200 Ok

Date: Thu, 03 Jul 2008 21:31:17 GMT

Content-Type: text/xml

<SavingGoal>

  <Id>1</Id>

  <ExternalItemId>12345</ExternalItemId>

  <Name>Porsche 911</Name>

  <StartingAmount>0.00</StartingAmount>

  <GoalAmount>100000.00</GoalAmount>

  <CurrentAmount>0.00</CurrentAmount>

  <EndDate>12/25/2008</EndDate>

  <PaymentProviders>

    <PaymentProvider>

      <ProviderName>Paypal</ProviderName>

    </PaymentProvider>

  </PaymentProviders>

  <Contributions/>

  <RecordVersionNumber>1</RecordVersionNumber>

</SavingGoal>

Reading a Saving Goal by id

Client:

GET http://www.wishpot.com/api/savings?Id={id}&ApiKey={RecordOwner} HTTP/1.1

GET http://www.wishpot.com/api/SavingGoal/{id}?ApiKey={RecordOwner} HTTP/1.1

Server response:

HTTP/1.1 200 Ok

Date: Thu, 03 Jul 2008 21:31:17 GMT

Content-Type: text/xml

<SavingGoal>

  <Id>1</Id>

  <ExternalItemId>12345</ExternalItemId>

  <Name>Porsche 911</Name>

  <StartingAmount>0.00</StartingAmount>

  <GoalAmount>100000.00</GoalAmount>

  <CurrentAmount>1.00</CurrentAmount>

  <EndDate>12/25/2008</EndDate>

  <PaymentProviders>

    <PaymentProvider>

      <ProviderName>Paypal</ProviderName>

    </PaymentProvider>

  </PaymentProviders>

  <Contributions>

    <Contribution>

      <Id>1</Id>

      <Amount>1.00</Amount>

      <Date>5/28/2008</Date>

      <Contributor>Mom</Contributor>

      <Message>Happy Birthday!  Good luck saving up for the Porsche</Message>

      <Status>Settled</Status>

      <ProviderName>PayPal</ProviderName>

      <ProviderURL>https://www.paypal.com/...</providerURL>

      <RecordVersionNumber>1</RecordVersionNumber>

    </Contribution>

  </Contributions>

 <RecordVersionNumber>1</RecordVersionNumber>

</SavingGoal>

Reading the contributions for a Saving Goal

Client:

GET http://www.wishpot.com/api/SavingGoal/{id}/Contributions?ApiKey={Re... HTTP/1.1

Server response:

HTTP/1.1 200 Ok

Date: Thu, 03 Jul 2008 21:31:17 GMT

Content-Type: text/xml

<Contributions>

  <Contribution>

    <Id>1</Id>

    <Amount>1.00</Amount>

    <Date>5/28/2008</Date>

    <Contributor>Mom</Contributor>

    <Message>Happy Birthday!  Good luck saving up for the Porsche</Message>

    <Status>Settled</Status>

    <ProviderName>PayPal</ProviderName>

    <ProviderURL>https://www.paypal.com/...</providerURL>

    <RecordVersionNumber>1</RecordVersionNumber>

  </Contribution>

</Contributions>

Deleting a Saving Goal

Client:

DELETE http://www.wishpot.com/api/SavingGoal/{id}?ApiKey={RecordOwner} HTTP/1.1

Server Response:

HTTP/1.1 200 Ok

Date: Thu, 03 Jul 2008 21:31:17 GMT

Content-Type: text/xml

Contributing to a Saving Goal

This is a multi-step process consiting of first creating the contribution, then redirecting the user to the payment provider so they can enter their payment details on the providers site. The payment provider is responsible for redirecting the user back to the client's site and for posting an update on the transactions to the contributions service.

 

Client:

POST http://www.wishpot.com/api/SavingGoal/{id}/Contributions?ApiKey={Re... HTTP/1.1

<Contribution>

  <Amount>1.00</Amount>

  <Date>5/28/2008</Date>

  <Contributor>Mom</Contributor>

  <Message>Happy Birthday!  Good luck saving up for the Porsche</Message>

  <ProviderName>PayPal</ProviderName>

</Contribution>

Server:

HTTP/1.1 200 Ok

Date: Thu, 03 Jul 2008 21:31:17 GMT

Content-Type: text/xml

<Contribution>

  <Id>1</Id>

  <Amount>1.00</Amount>

  <Date>5/28/2008</Date>

  <Contributor>Mom</Contributor>

  <Message>Happy Birthday!  Good luck saving up for the Porsche</Message>

  <Status>Submitted</Status>

  <ProviderName>PayPal</ProviderName>

  <ProviderURL>https://www.paypal.com/...</providerURL>

  <RecordVersionNumber>1</RecordVersionNumber>

</Contribution>

At this point the client is responsible for redirecting the user to the <ProviderURL>. On the payment provider's site the user may complete or cancel the transaction.  Either action will redirect the user first to the contribution service which will update the status of the contribution and then back to the client's site (ConfirmationUrl or CancelUrl) with the id of the contribution as an argument (Id={id}).  At this point the client has completed it's transaction with the contributions service for that contribution.

 

Loading a Contribution by Id

Client:

 

GET http://www.wishpot.com/api/Contribution/{id}?ApiKey={RecordOwner} HTTP/1.1

 

Server Response:

HTTP/1.1 200 Ok

Date: Thu, 03 Jul 2008 21:31:17 GMT

Content-Type: text/xml

<Contribution>

  <Id>1</Id>

  <Amount>1.00</Amount>

  <Date>5/28/2008</Date>

  <Contributor>Mom</Contributor>

  <Message>Happy Birthday!  Good luck saving up for the Porsche</Message>

  <Status>Submitted</Status>

  <ProviderName>PayPal</ProviderName>

  <ProviderURL>https://www.paypal.com/...</providerURL>

  <RecordVersionNumber>1</RecordVersionNumber>

</Contribution>

Deleting a Contribution

Client:

 

DELETE http://www.wishpot.com/api/Contribution/{id}?ApiKey={RecordOwner} HTTP/1.1

 

Server Response:

HTTP/1.1 200 Ok

Date: Thu, 03 Jul 2008 21:31:17 GMT

Content-Type: text/xml