app state transitions - heterogeneous collections vs links to resources that are relationship representations?

[tom_b]

Hi,

I've been reviewing the collection+json format as I design a restful api.  My thinking on handling resource relationships feels murky.

API clients will be able to link and unlink resources.  My resources include:

Medical studies

Patients

Samples for research

These three all map well to the collection pattern and designing the collection+json representation is similar to most examples I've seen.  But the relationships that can be created/modified in application state changes seem to lead to two design choices.

(1)  Use an actual collection to model the relationship.  For example, I could have a Cj representation StudyPatients (patient items on a single study item) that was a link from a study item and a Cj representation PatientStudies (study items on a single patient item) that was a link from a patient item. This choice seems straightforward, but also close to simply exposing a database schema where the study/patient relationship is a simple bridge table.  This would seem to force logic complexity onto the api clients.

(2)  Use a heterogeneous collection for both the study and patient resource representations.  In this case the Cj data items for a single study would include the study specific attributes and also patient items.  This would seem to simplify api client development although some clients would get representations back with extraneous data.  Also, I'm really not sure what a template for this heterogeneous collection would look like - does it even make sense to talk about a template for one of these without considering one of the embedded or inline extensions?

I feel like (1) may be the right choice here because some api clients will only deal with subsets of resources.  I'm also in a position where I'm taking several existing applications in our environment and trying to figure out how to provide a clear api to work with the multiple resources in each.  What is currently happening is a "no-design" set of ad-hoc hooks between apps that lead to confusion about what resources are handled in each app separately.

I'm quite curious if other Cj implementors have strong opinions about this scenario.  I mostly seem to find examples of single resources.

Thanks and as I make prototypes, I'll return to post more specific examples of Cj representations involved . . . .

[mca]

FWIW, the first thing i ask in cases like this is "what are users going to want as a representation?" i am interested in what users want/need, not the data model or the media type, etc.

you can use Cj to represent many kinds of collections including the heterogeneous ones (i usually use a "type" data element to group like kinds of items and a "parent" or "childOf" to match related items).

in many implementations i work on, there is no single representation answer anyway. some users are not *allowed* to see related items, some rarely need the related items and a single entry in the main item's link collection is the best answer for that group. 

in other cases, a master edit experience *requires* a rather large representation of the collection of all related items in a single response -- even more then parent-child, but multilevel full item heterogeneous collections.

i'd be interested in hearing how others are handling these types of use cases w/ Cj.

cheers.

mca

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

--
You received this message because you are subscribed to the Google Groups "Collection+JSON" group.
To unsubscribe from this group and stop receiving emails from it, send an email to collectionjso...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.