rest - RESTful API design debate: complex query for restful endpoint -

rest - RESTful API design debate: complex query for restful endpoint -

i'm designing restful api big collection of reporting data, pass complex set of parameters in codeblock below. i'm debating between using post , endpoint. team fellow member seem favor not sure best way of passing amount of info parameters, best thought far have 1 parameters called jsonparams have of below json encoded

{ "filters": [ { "field": "metric-name", "gt": (float/int), "lt": (float/int) }, { "field": "metric-name-2", "gt": (float/int), "lt": (float/int) } ], "sort": [ { "field": "metic-name", "order": "asc"/"desc" }, { "field": "metic-name-2", "order": "asc"/"desc" } ] "limit": 100, "offset": 0 }

if you're adding info resource or creating resource utilize post. acquire existing resource, not alter state of resources.

if argument go crazy serialized parameter based request kind of percived simplicity, you're not going adhearing rest.

now, if you're retrieving resources (no creation), utilize get. while prefer human typable parameters, it's not required. if situation 100% retrieval encode entire set into giant encoded param string, i'd suggest @ to the lowest degree splitting out bit improved sanity doing like:

/resource?filters=urlencoded_filter_array&sort=urlencoded_sort_array&offset=0&count=100

or go more explicit like:

/resource?filter1=urlencoded_filter_json&filter2=urlencoded_filter_json .... sort2=urlencoded_sort_json&offset=0&count=100

or (my favorite) explicit broken out set of params

/resource?filter1_field=bah&filter1_gt=1.0&filter1_lt<2&filter2_field=boo&filter2_lt...

i final 1 because there's no encodeing/decoding of json , url encoding entire json string. format easy decipher in access logs , problem shoot. it's cacheable, if parameter order gets changed, proxy caches can still work this, whereas encoding of filters in json object if moved around exclusively different values far proxies concerned. me it's rest friendly (if makes sense), though first 2 examples fine rest requests.

the added work parse parameter name isn't much fuss. simple method convert json parameter string , simple 1 re-hydrate json object explict filter1_xyz format.

rest restful-architecture