REST API Design for Complex Operations

Question

Queries -

Working on building a Rest API to support search/filtering of transactions. Below are the two requirements, api is expected to support

Retrieve list of transactions by an array of [transactionid] - minimum is 1
Retrieve list of transactions by ( (transactionType=Sale OR transactionType=Refund) AND storeid=XXXX))

I am looking to design this as POST request with assuming search as resource something like the below. I am puzzled on second requirement above in complex querying with "AND" "OR" operations. Any inputs around it will be deeply appreciated. API is expected to supported search of transactions on varied attribute combinations

Design for Requirement 1

POST /sales-transactions/search
{
  searchrequestid:xxxxxx
  transactionids:[1,2,3,4,..]
}

Does this answer your question? [REST API Best practice: How to accept list of parameter values as input](https://stackoverflow.com/questions/2602043/rest-api-best-practice-how-to-accept-list-of-parameter-values-as-input) — pringi, Mar 01 '21 at 14:27

score 2 · Answer 1 · answered Mar 01 '21 at 14:13

If "retrieve" is an essentially read only operation, then you should be prioritizing a design that allows GET, rather than POST.

Think "search form on a web page"; you enter a bunch of information into input controls, and when you submit the form the browser creates a request like

GET /sales-transactions/search?searchrequestid=xxxxxx&transactionIds=1,2,3,4...

Query parameters can be thought of as substitutions, the machines don't care which parameters are being used for AND and which are being used for OR.

select * from transactions where A = :x and B = :y or C = :z

GET /sales-transactions/search?A=:x&B=:y&C=:z

Because the machines don't care, you have the freedom to choose spellings that make things easier for some of your people. So you could instead, for example, try something like

GET /sales-transactions/AandBorC?A=:x&B=:y&C=:z

It's more common to look into your domain experts language for the name of the report, and use that

GET /some-fancy-domain-name??A=:x&B=:y&C=:z

When we start having to support arbitrary queries through the web interface, and those queries become complicated enough that we start running into constraints like URI lengths, the fall back position is to use POST with the query described in the message body.

And that's "fine"; you give up caching, and safety, and idempotent semantics; but it can happen that the business value of the adhoc queries wins the tradeoff.

REST API Design for Complex Operations

1 Answers1