Unsupported/unknown arguments handling

Q: How should a Provider handle unknown or unsupported parameters defined by the Query Specification ?

There are 2 possible options: fail silently or ignore the parameter.

Example 1 failing silently to handle oslc.where and returning all records will change the semantics of a report/document requesting only the "high priority" requirements.

Example 2 failing silently to support oslc.select will preserve the semantics of the report/document but will generate additional network traffic.

So depending on the parameter, consumer and use case one or the other of the options is preferable. This raises a problem on what consumers should expect from providers and viceversa.

Q: Should the OSLC Reporting Specification request providers to suport all parameters?

Marking as mandatory only a subset of the requirements, and facing the prospect of new parameters introduced by future specs, can confuse providers and consumers alike. Hence the proposal is either to mark all parameters mandatory or none.

All parameters mandatory

The provider must support all parameters

This is the ideal scenario for the consumer but raises the bar for the provider to support the Query Spec. Having server side support for filtering, sorting and property selection ensure an optimal reporting/document generation experience: the consumer gets exactelly what it needs and can consume the data with minimal pre-processing.

All parameters optional

The provider ignores unknown/unsupported parameters

Note "ignore" may have different meanings based on the parameter. The exact behavior needs to be documented by each provider.

This implies very little effort for a provider which already exposes a RESTfull API. On the other hand this approach puts the consumer in the awkward position of not knowing if the parameters handled or not. Even if the consumer can compensate the of server side implementation for some parameters it needs to know if the server handles them or not. And with the server silently ignoring parameters this is not a straightforward task.

All parameters optional with strict mode (oslc.strict)

Lowering the bar for Query Spec support favors the adoption of the OSLC Reporting with providers. The consumer's problem in this case is that it needs to know parameter is supported or not. This can be achieved by providing the information in the resource shape or reading it from the provider manuals. A simpler option is to allow the consumer to specify how the provider handles unsupported/unknown parameters in the request via the oslc.strict parameter.

Note the oslc.strict parameter is similar to the "pedantic" flag found in many compilers. Example GNU C++ Compiler

Note Support for this parameter is mandatory. The default value for oslc.strict should be true so that consumers can identify immediately the provider's capabilities and prevent incorrect documents/reports being created.

The parameter's possible values are:

oslc.strict = true the provider must return a HTTP 400 - Bad Request error if it encounters any parameter it cannot handle

http://example.com/bugs?oslc.where=cm:severity="high"&oslc.orderBy=-dc:created&oslc.limit&oslc.offset=100&oslc.strict=true

Result this request will succeed only if the provider supports all the parameter: oslc.where, oslc.orderBy, oslc.limit.

oslc.strict = false the provider may silentlly ignore unknown/unsupported parameters

http://example.com/bugs?oslc.where=cm:severity="high"&oslc.orderBy=-dc:created&oslc.limit&oslc.offset=100&oslc.strict=false

Result this request will always succeed even if the provider supports none of the other parameters.