REST API url 滤波设计

Question

I've been looking around and most folks seem to recommend designing filtering with ranges in REST API URLs using the bracket notation (eg /resource?weight[gte]=1&weight[lte]=5 ) or some variation of this...

But is there any reason we can't just use a delimiter and document the expected order in API docs? eg /resource?weight=1_5 ...where the API docs would inform the client that pattern is min_max

Are there any pros or cons to both the above that would warrant one over the other?

Answer 1

Are there any pros or cons to both the above that would warrant one over the other?

Yes.

First: the URI production rules in RFC 3986 do not permit LEFT SQUARE BRACKET and RIGHT SQUARE BRACKET in the query part of the URI - those characters have to be pct-encoded.

Second: we don't have a good way to communicate bespoke query value delimiters to general purpose components. What you are proposing to do here is analogous to having a single input control for two values - and telling the human being using the form that they should type text using a specific schema. But we really don't have a standardized language for that.

There's already a lot of work done in standardizing URI Templates , your default options should be limited to the mechanisms described there. In a code review, I'd push back against your proposal if you didn't have compelling supporting evidence ready.