Endpoints /studies/{studyOID}/snapshots functionality concerns

[mhungria]

Why including separate endpoints for snapshots?

1. I was assuming the studies/{study}/datasets and studies/{study}/dataset endpoints will include parameters to select standard and snapshotID={snapshotID}.
2. Overall, Dataset-JSON refers to snapshots (no transactional data). Having separate endpoints for snapshots as opposed to a parameter to filter on may be confusing.
3. As I interpret the revisions to the specs, we won't be able to get a subset of datasets from a given snapshot.

[swhume]

I expanded the Snapshot and Define endpoints a bit and gave them a similar structure. Snapshots are just archived off studies, so you can grab snapshot datasets the same way you grab a study dataset.

When you request a Study it will include the list of available Snapshots, so that's the easiest way to load one. Once you've loaded a snapshot (which is the same model as Study), you can select what datasets you want to see from the snapshot.

I added (and will post this tonight) an additional endpoint, GET /studies/{studyOID}/snapshots/{label}/datasets/{datasetOID}. This is a way to request a specific dataset that's part of the snapshot. Most will just grab the dataset URL from what's returned using the snapshot endpoint (basically the same as what is returned for a Study).

I'll implement this in the API POC over the next couple of weeks.

[mhungria]

Thanks, Sam!
It is difficult to comment further without seeing the actual updates made to the specs.

In the mean time, I'll add a couple of points after reviewing your responses:

4. If a study is created without implementing snapshots initially (equivalent to say snapshots not added) and later, a need to create a separate snapshot, would "Snapshots are just archived off studies" mean the need to explicitly copy the study as snapshot x?
5. There may be a need to add a 'lock' attribute to a study (or any of its snapshots) to avoid updates at a given point in time.
6. What would actually entail appending records to a dataset? A new Dataset-JSON file top-level properties would need to be updated as well.

[swhume]

The updated spec is available now. I still need to implement these latest updates in the POC.

4. A study is created w/o snapshots. At any point after that time, a snapshot can be created. Snapshots copy the current study into a immutable copy. No update is available to a snapshot. You can delete and existing snapshot and add a new one, though.
5. The snapshots are immutable. They cannot be updated or appended to, but they can be deleted.
6. You could create a snapshot. Then append records to a dataset in that same study. Then you could compare the current study dataset to the snapshot version of the dataset.

I'll create one or two sequence diagrams for this and add them to the UG after PR.