Clarify if file- or api- style access should be used for resources located at URL endpoints

[markboots]

We came across something small while implementing the retrieve API:

The Resource specification currently says that the resource can be located at a file or a URL, consistent with the Data Packages spec:

a path must be provided for the Resource. The Resource path shall point to a file reference (for packages stored on disk) or a URL.

For resources stored at URLs (e.g. http://my.demoserver.com/flowpackages/2347832/data.json), this leaves ambiguity on whether the resource should be accessed:

• file-style (e.g. one static file hosted at that URL, with all responses in that file)
• api-style (supporting pagination and filtering, etc. according to the API access specification, where the response is encapsulated in the JSONApi container.)

Suggestion: add a new optional parameter to the Resource:

• access-method is an optional parameter, and can be api or file. If the access method is api, it indicates the resource can be queried using the API Access specification, with support for pagination and filtering. If the access method is file, it indicates all responses are available in a static JSON file. The default if this parameter is not provided is file.

(Not sure what we should recommend and use as the default if not provided - suggestions? Or should this parameter simply be mandatory?)

(Example of what would be statically hosted at the URL in file-mode:

[
  [ "2017-05-23T13:35:37.356-04:00", 20394823948, 923842093, "ae54d3", "female", {"option_order": ["male","female"]} ],
  [ "2017-05-23T13:35:47.012-04:00", 20394823950, 923842093, "ae54d7", "chocolate", {} ],
  [ "2017-05-24T15:15:37.981-04:00", 20394823952, 923842086, "ae54d3", "male", {"option_order": ["male","female"]} ],
  [ "2017-05-23T15:16:12.005-04:00", 20394823953, 923842086, "ae54d7", "vanilla", {} ],
  [ "2017-05-23T15:16:20.781-04:00", 20394823954, 923842086, "ae54d8", 196, {} ],
  [ "2017-05-23T15:16:38.119-04:00", 20394823955, 923842086, "ae54da", "I am feeling curious.", {"type": "text", "language": "eng"} ],
  [ "2017-05-23T17:25:12.722-04:00", 20394823956, 923842093, "ae54da", "https://myexampleflowserver.org/resources/audio/20394823956.ogg", {"type": "audio", "language": "eng", "format": "audio/ogg"} ],
  [ "2017-05-23T17:25:47-04:00", 20394823957, 923842093, "ae54db", "[35.678323, -108.25343]", {} ]
]

[ggiraldez]

I'm not sure about this. What if an implementation wants to offer both methods?

Maybe we can use a single property path and differentiate via the reported MIME type. JSON API has a registered MIME type: http://jsonapi.org/#mime-types. This only applies to URL type paths of course.

An alternative, which deviates from the Date Resource Package is to use a different property for API based access. data-endpoint or something similar?

[markboots]

Thanks @ggiraldez , good question. If an implementation wanted to offer both... they would need to be at different paths, right?

I'm not sure about differentiating via MIME type...

I also realized from your post that we break the Data Resource Package if we use the path for the API endpoint... as software expecting Data Resource Packages would expect a data file there.

So I like your proposal to only use path for the file-mode access. api-data-url could be an optional additional parameter with the API URL. If path is null, then it means only API access is supported, and api-data-url must be provided.

[markboots]

Thumbs up during discussion on the call!