Query Strings and opacity

[Joshua Graham]

G'day all,

I am using opaque URIs. I have a single well-known root resource from which all other resources can be found. The URIs are generally hierarchical, but not always -- particularly when linking to resources that are related but handled by a different API or micro service. As such, there are no URI templates published for consumers to interpolate.

However, I have the occasional resource where a filter may be applied, typically to reduce the number of entries in an index type of resource, or to ask for extra detail that is otherwise optional.

As this changes neither the address nor the representation of the resource, I feel the URIs are still opaque, even when there is a query string appended.

The problem is the opacity of names of the parameters and their legal/useful values.

How do you feel about the "templating" of optional query strings? It's like a search form, where the method is (usually) GET.

Do I publish RDF or indeed an HTML document containing a FORM which describes the allowed parameters and type information for values (to the extent that type information can be derived form those formats)?

The benefit of this is a certain amount discoverability and also indicates canonical ordering of parameters (helps with caching, and mis-ordered queries can be canonicalized through a 301/308 redirect).

The drawback is it still requires a lot of out-of-band knowledge (the consumer's developer is doing much of the work to interpret the form and what it means) or relaying semantics to upstream consumers to determine what parameters to use and which values to fill them with.

I'm tending to limit these sorts of things where possible, preferring to offer a pre-baked resource that does away with the need for the query string, but for those that are left (with arbitrary values or combinatorial complexity) just publish documentation in the API that says what the parameters are and how to use them.

Thoughts?

[Rushforth, Peter]

 

 

> How do you feel about the "templating" of optional query strings? It's like a search form, where the method is (usually) GET.

 

I feel good!

 

> The drawback is it still requires a lot of out-of-band knowledge (the consumer's developer is doing much of the work to interpret the form and what it means)

 

That is not out of band, if as part of the format documentation, you document the names of the template variables and provide values for them in the response body. 

 

> Do I publish RDF or indeed an HTML document containing a FORM which describes the allowed parameters and type information for values (to the extent that type information can be derived form those formats)?

 

I'm not sure I understand the qualification, but the template and their values *are* a form of form.  What is being templated is the potential request, and suggested values or restrictions on input (e.g. patterns) are part of the form.  The beauty of this is that those values can vary at run time.

> I'm tending to limit these sorts of things where possible, preferring to offer a pre-baked resource that does away with the need for the query string,

I think that is the right approach - keep it simpl.  The client will get complex.  I think the 'right thing to do' is to provide code-on-demand in the form of js to support your choice of templates, but that is an area that I'm only just getting some experience in now.

> but for those that are left (with arbitrary values or combinatorial complexity) just publish documentation in the API that says what the parameters are and how to use them.

 

I think you should document the template variables, and where to look for them in the format, *not* the parameters - and they don't have to be the same thing.  That way the contract is with your format, not with the server api.

 

Cheers,

Peter Rushforth

---

From: restinp...@googlegroups.com [mailto:restinp...@googlegroups.com] On Behalf Of Joshua Graham
Sent: May 8, 2013 21:36
To: restinp...@googlegroups.com
Subject: Query Strings and opacity

--
You received this message because you are subscribed to the Google Groups "restinpractice" group.
To unsubscribe from this group and stop receiving emails from it, send an email to restinpractic...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.