wufm/osdi-docs — pull request #85 by joshco (2014-02-06 10:55:52+00:00)
Title: Transport: Feature/fuzzy linking

While working on the "actions" proposal, something in my brain clicked or broke.
Another way to solve our problem may be "fuzzy linking"

See the Pull Request for all the details, but...

### Fuzzy Linking (fuzzy-link)
Fuzzy linking allows a client to link two resources together by providing matching criteria rather than an explicit identifier.

This can be useful in actions where the intent is to create a new resource, such as a donation, and either associate it with an existing Person or create a new associated Person resource.

Which course of action to take is not known at the time of the request, and the client has little interest in researching the existence of Person.

### Add "match" element
With FL, when you would normally specify a link, you can specify matching criteria. Right now I have it placed inside request body _link elements where we use "osdi:match" instead of "href"

````javascript
POST /api/v1/urlto_donations_collection

{
// resource specific attributes
"donation_date" : "2013-11-19T08:37:48-0600",
"amount" : 50.00,
"currency" : "USD",

"_links" : {
"person": {
"osdi: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)
}
},
}

201 Created
Content-Type: application/json

{

"donation_date" : "2013-11-19T08:37:48-0600",
"amount" : 50.00,
"currency" : "USD",
// continuation of donation resource attributes
"_links" : {
"self" : { "href" : "http://link/to/this/new/donation"},
"person" : {
"href" : "http://link/to/associated/person"
"osdi:match_response" : {
"result" : "created",
"href" : "http://url/to/matched/or/created/person"
"identitifiers" : [ "voterlabs:1234", "acme:3516516" ]
},
}
}
}
````