ajax.url — cljs-ajax 0.8.4

At first blush, it's pretty bizarre that an entire file is devoted to one
function, namely params-to-str, which just takes a map and converts it to a querystring. However, it turns out that people sometimes want to encode fairly complex maps and the behaviour in the presence of vectors/arrays is controversial.

The basic question is: what {:a [1 2]} be encoded as? The correct answer as far as ring is concerned is a=1&a=2. This is also true of most Java implementations, ASP.NET, Angular, Haskell and even old-school ASP. This is called vec-strategy :java in the code. Rails and PHP, however, prefer a[]=1&a[]=2, which has an obvious implementation in a dynamic language. This is called vec-strategy :rails. Finally, there's what cljs-ajax (mistakenly) did between versions 0.4.0 and 0.6.x: a[0]=1&a[2]=1, which is called vec-strategy :indexed. This is retained mostly for people who need to keep compatibility with the previous behaviour.

None of these are the "correct answer": the HTTP standards are silent on the subject, so you're left with what your server accepts, and different servers have different conventions. Worse, if you send the wrong convention it gets misinterpreted. Send strategy :rails to a :java server and you get { "a[]" [1 2]}. Worse, send strategy :java to a :rails server and you get { "a" 2 }. So it's important to know what your server's convention is.

The situation for maps is simpler, pretty much everyone encodes {:a {:b 1}} as "a[b]=1". That is, assuming they process it at all. The HTTP spec is similarly silent on this and your server may get your language's equivalent of { "a[b]" 1 }. In cases like this, you have two choices 1) write your own server-side decoder or 2) don't ever send nested maps.

If you ever wanted to consider exactly how bad the effect of supporting a wide range of use cases, consider that this was the original code:

(defn params-to-str [params] (if params (-> params
clj->js structs/Map. query-data/createFromMap .toString)))

This code remains completely correct for at least 90% of actual users of cljs-ajax. Now we have ~50 SLOCs achieving much the same result.

params-to-str clj/s

(params-to-str vec-strategy params)

vec-strategy is one of :rails (a[]=3&a[]=4) :java (a=3&a=4) (this is the correct behaviour and the default) :indexed (a[3]=1&a[4]=1) params is an arbitrary clojure map

url-request-format clj/s

(url-request-format)

(url-request-format {:keys [vec-strategy]})

The request format for simple POST and GET.