wufm/osdi-docs — pull request #86 by joshco (2014-02-06 11:03:37+00:00)
Title: Transport: Actions Feature

Here is an "actions" based proposal per last week's call discussion

For a compare, look at this URL:
https://github.com/joshco/osdi-docs/compare/feature;actions

## Overview
OSDI used a combination of approaches to provide flexible reading of data, simple operations for simple scenarios, and general purpose CRUD access.

OSDI Compliant endpoints achieve this through the following capabilities

### RESTful Reading of Data (rest-read)
Reading of data, or querying resources, is done via traditional REST and Hypermedia practices. OSDI uses HAL for hypermedia and OData query language to give a rich and flexible way to express queries

### Actions (actions)
OSDI also allows a client to perform actions, sometimes known as scenarios or methods, when the scenario is 'action oriented' vs 'data oriented' such as singing up a supporter, recording a donation, or rsvping for an event.

Certain common actions have been specifically defined to include any needed semantics to allow a client to perform an action in a single HTTP request/response.

### Direct Data Updates (rest-write)
There will always be an unbounded set of scenarios such that defining specific actions for each would be impractical. For scenarios outside Actions, OSDI provides direct RESTful data access. By using the common RESTful operations, along with hypermedia, virtually any scenario can be accomplished.

## Example Action: Record Donation
````javascript
POST /api/v1/urltoaction/record_donation

{
"person_match": {
"given_name" : "Testy",
"family_name" : "McTesterson",
"address1" : "124 Foobarrio St",
"postal_code" : "99999",
"email_address" : "testy@example.com"
"identifiers" : [ "voterlabs:1234" ]
"options" : {
"update" : true, // update the matched person with
//included info (true) or use only for matching
//(false)
}
},
"donation_date" : "2013-11-19T08:37:48-0600",
"amount" : 50.00,
"currency" : "USD",
}

201 Created
Content-Type: application/json