RESTful查询API设计

Question

I want to ask what is the most RESTful way for queries, I have this existing API

/entities/users?skip=0&limit=100&queries={"$find":{"$minus":{"$find":{"username":"markzu"}}}}

Easily the first parts of the query, skip and limit are easily identifiable however I find the "queries" part quite confusing for others. What the query means is to

Find every User minus Find User entities with username 'markzu'

The reason it is defined this way is due to the internal database query behavior. Meaning in the NoSQL database we use, the resource run two transactional queries, first is to find everything in the User table minus a find User with a username that was specified (similar to SQL) -- boolean operations. So in other words, the query means, "fetch every User except username 'markzu' "

What is the proper way to define this in RESTful way, based on standards?

Answer 1

What is the proper way to define this in RESTful way, based on standards?

REST doesn't care what spelling you use for resource identifiers, so long as your choice is consistent with the production rules defined in RFC 3986 .

However, we do have a standard for URI Templates

A URI Template is a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion.

You are already aware of the most familiar form of URI template -- key-value pairs encoded in the query string.

?skip=0&limit=100&username=markzu

That's often a convenient choice, because HTML understands how to process forms into url encoded queries.

It doesn't look like you need any other parameters, you just need to be able this query from others. So a perfectly reasonable choice might be

/every-user-except?skip=0&limit=100&username=markzu

It may help to think "prepared statement", rather than "query".

The underlying details of the implementation really shouldn't enter into the calculation at all. Your REST API is a facade that makes your app look like an HTTP aware key value store.