Handling a GET request that depends on client paramters

In most common scenarios, a GET on the resource URL returns an RDF response with information about this resource.

I have a scenario where the server expects some parameters from the client, in order to return a correct response.
For example, depending on “startTime” & “endTime” parameters, the value of a certain property - say dcterms:description will differ.
The properties startTime & endTime are themselves not necessarily even part of the resource description.

The client needs to link to a specific resource description that is parameterized.

How can I best model this using OSLC?
I am thinking of the approach below. I wonder if anyone can identify any problem with that? Is there any other way I can solve this?

Define the resource URL with query parameters (http://example.com/resource/r1?start_time=20201101&end_time=20201201) or path paramters (http://example.com/resource/r1/start_time/20201101/end_time/20201201).

I suspect this ought to be fine, since the query part is a valid part of the resource URL?
But then it looks like there is an endless set of resources, since the paramters can be of any value.

With this approach, I am also thinking that the base “http://example.com/resource/r1” can be seen as a ServiceProvider, with an OSLC Query service that can return all possible resources (with URLs with query/path parameters)

Can anyone see a problem with this approach? Is there any other way I can solve this?

Jad, OSLC does not define what it means to put HTTP query parameters on a URL other than selective properties or OSLC Query. So the URL http://example.com/resource/r1?start_time=20201101&end_time=20201201 would be a custom URL that is specific to that server.

You could use OSLC Query for this, and if there is a select clause, you would get the (single) resource in-lined in the response. The client would have to parse the response enough to get the resource URL.

It sounds like your requirement is more like a query than a GET of a specific resource. In whiich case, the server should declare an appropriate OSLC query capability in one or more OSLC service providers referenced by the service provider catalog, and that query capability should support querying on the properties of interest. It would be good practice for the query capability to reference a resource shape that defined the queryable properties.

Thanks Jim & David

Sure, as @Jim suggests I can use a Query with a select clause. And that would return the single resource in-lined. But the question remains: What would the URL for that in-lined resource be?
You also say that “the URL would be a custom URL that is specific to that server.”. Is there a problem with that? Isn’t that always the case? I hope/guess that OSLC doesn’t have any reservations against adding HTTP query paramters to a URL.

@David! The ultimate aim is not really the Query capability. The client knows exactly what the resource is. namely, http://example.com/resource/r1. It’s just that that resource is to be represented differently depending on the parameters that the client can send.
But indeed, I was thinking of having a Query capability on the ServiceProvider.
But as I mentioned to Jim above, what are the URIs in the Query response?

Hi Jad,

If your resources are really changing, it may be that they include an agregate data. Then wouldn’t it more reliable (and easier) to consider your resources, say “water counters”, always including the latest known value for the counter. Then have “water consumption” resources, which would be created either “each time” we get the data from the counter, or computed based on the smallest time slot the customer would feel appropriate.
Then you can use Query to get the consumptions from start to end. Which will get you multiple results, which you can then agregate. That’s where I differ from what you’re looking for I guess… but that would make things more reliable IMO.

Sorry to map your description to a real world example, but I find it easier to reason about. And I hope it’s not too far from what you’re facing :sweat_smile:… else… just forget about that post!!!

Hi Frej

Thanks for the input. I think my parameter examples (StartTime & endTime) might be misleading, since the issue is not about the values changing over time.
Let me give another parameter example: “viewDetails”, which can take a value of “simple” or “detailed”.
If client sends “?viewDetails=simple”, then the server will return one value of “description” field.
If client sends “?viewDetails=detailed”, then the server will return another value of “description” field, which is much longer.

A simple example just to illustrate the point. The resource does not change over time. The resource is just represented differently, based on what the client sends.

Why not apply the “Compact” strategy here?
Keep a single URI for the resource in the “complete” version. Then request a different representation by specifying a different accept header for the version that has “less information”.

@jad I would consider /resource/full/123 and /resource/short/123 different resources. If they are the same, I would vote for a same URI.

Regarding query parameters and custom HTTP headers: I think if the content changes, not just the representation, it is more fair to use query parameters. URI classes can compare them, users can bookmark them etc.

WADL for RESTful services defined those a while ago https://en.wikipedia.org/wiki/Web_Application_Description_Language#Example (see line starting with <param name="appid") and I feel having something similar is worthwhile to have a way to define something like


That would allow you to request a resource that applies in the EU (http://vocab.getty.edu/tgn/7030305 is a standard RDF id for EU) jurisdiction (dcterms:coverage allows to point to a jurisdiction). For example, you may return more private data only if this flag is set. oData spec actively relies on query params that begin with @ and $ in addition to WADL. You can paste this URI into https://www.freeformatter.com/url-parser-query-string-splitter.html to see what it produces.

Note that HTTP natively supports duplicate query parameters so http://example.com/resource/r1?@oslc$schema:startTime=20201101&@oslc$schema:endTime=20201201&@oslc$dcterms:coverage=http://vocab.getty.edu/tgn/7030305&@oslc$dcterms:coverage=http://vocab.getty.edu/tgn/7011731 is correctly parsed as having these parameters (letting Switzerland join the party here):

We need the @oslc prefix to enforce our non-global hardcoding of prefixes to specific URIs, in my opinion. But we can discuss this further.