Feedback on the alpha release - Part 1

[emiliom]

@cdesyoun, here's a first batch of comments based on my assessment of the ODM2 REST API with my Marchantaria use case data. For reference, here is the IPython notebook demo I created a week ago, that I shared with the ODM2 team.

Organizations and grouping of service requests

Individual requests are either grouped in the Observations service type, or un-grouped / stand alone. This makes sense. But some reorganization would be helpful, for consistency with respect to the response type:

• For consistency, all ungrouped, top-level requests should be "granular" and provide responses focused on the entity (methods, sites, etc) and its associated, supplementary entities.
• /datasets/{datasetUUID} returns an Observations-type response, so it should be moved to that service group.
• Observations/value is unlike all other Observations requests, as it's the only one that returns result values. It's misleading/confusing to have it under Observations.

Restructure Observations/value response to be more generic and independent of ResultType

Currently the JSON response uses keys that mirror the table values in the RDBMS implementation. eg, for Measurement ResultType, the values will be available in the hierarchy MeasurementResult.MeasurementResultValues. This means that if a timeseriesCoverage ResultType is being requested, the object (key) hierarchy will be different, and will probably be like this: TimeSeriesResult.TimeSeriesResultValues. This makes it much more difficult to access result values independently of ResultType. I strongly suggest that the value request always return the same object names, which are in effect the "class" names (sort of): Results.ResultValues. The content (keys) of each of those objects will vary depending on the ResultType, but the ResultType should always be in the response, so a user can refer to it to infer which keys to expect for each ResultType.

Option for "lean" response

Some requests could really benefit from having an optional (or default) "lean" response, to reduce the size of the response. Specifically:

• /datasets/{datasetUUID}. In addition to dataset information, a lean response could include only ResultUUID and ResultType, for Observations-related information.
• Observations\value. This request returns the entire 'Observationsresponse (Results, Actions, Methods, SamplingFeatures, etc), in addition to the specific "ResultValue" information that's the actual focus of the request. That can get really huge, and is often unnecessary b/c avalue` request will probably be issued after having queried observations and selected a list of target ResultUUID's. The lean response should include only ResultUUID and ResultType, in addition to Result and ResultValues.

Miscellaneous

• Add variableName (VariableNameCV) and variableType (VariableTypeCV) requests to the variables request
• Some empty string properties are returned as an empty string, and some as JSON null literal. It's best to be consistent, unless there are specific reasons not to. I lean towards using JSON null. As examples, the samplingfeature request returns null literals, while the values request returns empty strings for MeasurementResult.XLocation

[cdesyoun]

@emiliom, I followed up your feedbacks below on my development:
Since you are using JSON format in your ipython notebook, I made an change on that format only.

1. Organizations and grouping of service requests
   For the consistency, I did reorganize the service groups and contents based on the ODM2 diagram.
   ODM2CORE: http://odm2.github.io/ODM2/schemas/ODM2_Current/diagrams/ODM2Core.html
   ODM2SamplingFeatures: http://odm2.github.io/ODM2/schemas/ODM2_Current/diagrams/ODM2SamplingFeatures.html
2. Restructure Observations/value response to be more generic and independent of ResultType
   I did it for multiple time series and specimen time series data.
3. Option for "lean” response
   I think it makes sense to me. I did it.
4. Miscellaneous
   I did it.

Since this is under development, I put these updates into my development side.
Please review it at this URL, http://sis-devel.cloudapp.net:9090/docs/
If this is OK for you, I will update them on my production side.

[emiliom]

Copying this update from @cdesyoun from odm2api issue 27, for reference: @emiliom and @valentinedwv, I updated ODM2 REST API that integrates with odm2api with Emilio's review comments. Test site is http://sis-devel.cloudapp.net/docs/.

[aufdenkampe]

Closing, given the recent reorg/refactor of the repo.