use SM derived models as REST API resources


It looks likes in some cases the RM types are not suitable to be used to commit data via REST APIs. In abstract SM there are references to other RM-shadow types that should be used also by REST APIs.

A recent discussion on slack:
Pablo Pazos [9:31 PM]
@channel I have a doubt about POST /contribution, is the idea to post the contribution first and then post the compositions with a reference to the existing contribution, or first post all the compositions then post the contribution referencing those compos?
Thomas Beale [9:40 PM]
The resulting effect has to be that all of that has to be committed at once, as an atomic transaction.
Pablo Pazos [9:57 PM]
I'm not sure if that is possible in REST with the current schemas
Sebastian Iancu [9:57 PM]
if I remember the discussions we had 2y ago, the intention was to POST a contribution+content
Pablo Pazos [9:58 PM]
I proposed a couple of years ago to have a resource CONTRIBUTION that can contain physically COMPOSITIONS (really VERSIONS), instead of having the OBJECT_REFs, which cause problems when you need the whole thing in one transaction
Sebastian Iancu [9:58 PM]
so no reference, but content itself
Thomas Beale [10:00 PM]
Yes, as a structure for committing, that is probably what is needed.
Sebastian Iancu [10:00 PM]
see in the POST example there is a {versions[].data: {}} (edited)
Thomas Beale [10:01 PM]
Which is why we have those special types in the abstract platform model, to describe exactly the correct commit forms - (edited)

Pablo Pazos [10:01 PM]
@sebastian.iancu is that enough for creating the contribution also? for instance the contribution needs an audit
or is the contrib.audit created by the server?
Thomas Beale [10:02 PM]
We can add a new structure there if we need, and it will become the new type of the relevant argument to the call
Pablo Pazos [10:03 PM]
@wolandscat I think that structure is the one Sebastian mentions, I think that works, just have the doubt about the CONTRIBUTION.audit ^
I agree, if that is different from any structure in the RM / Schemas, should be something specific in the SM for that one to represent that transaction
Thomas Beale [10:04 PM]
at a minimum, the update structure has to follow the UPDATE_VERSION and its UV_XXX children...
to allow for some data to be created on the server
Pablo Pazos [10:05 PM]
I guess this structure is a SET of those
and thinking about REST, maybe we should have schemas for those UPDATE_XXX structures, since we cant use a ORIGINAL_VERSION directly to commit data because the VERSION.contribution is required by the RM (the issue I raised some time ago was about this)
Thomas Beale [10:08 PM]
something like that, or could just have a single AUDIT_DETAILS
agree. I was trying to convince people for the last 2y that we need specific structures for commit through the API, particularly for REST, which has its dumb 'document' model that doesn't match most kinds of real data.
Anyway, whatever people can agree on for that structure, I am happy to document it in the SM model, so that we have a formal type to use.
Sebastian Iancu [10:19 PM]
i'm not sure what is the disagreement - is it about UPDATE_VERSION vs ORIGINAL_VERSION ? I'm also lately convinced about it (and about problems reported by @pablo.pazos), and I guess its not only me. We will need to formalized in the REST API specs


Sebastian Iancu

Raised By

Pablo Pazos


Affects versions