REST API设计查询

Question

I have a problem in deciding what to do in this case in REST API design.

here is my problem,

I have a resource domain model, which has a nested object, which is also a domain model.

you can imagine something like this

{
"name":"abc"
"type":{
        "name":"typeName",
        "description":"description"
       }
}

Now, i want to be able to fetch the outer model resources, based on the inner model and few more params.

for example, i want to fetch all outer model resources which have a given type and some params like page number, size etc.

So my questions,

1.the API should accept inner model in post, and return outer model, is it a good rest design?

2. How do i pass the extra params? It's a POST, can't put them in url, and can't put them inner model.

Should i create a new model, which contains these extra params and the type resource also? like

{
"page":"10",
"type":{
       "name":"typeName",
       "description":"description"
        }
}

Answer 1

If you are making a generic HTTP service, it's acceptable to use POST to send a complex query, and to get a response.

If you are trying to be RESTful, then this is a bad practice. You have two options. Option 1 is to find a way to encode your query in the URL, so you can use a GET request.

Option 2 is more involved. I wouldn't necessarily say that I would suggest this, but it's a method to get around the constraints of REST while having complex queries.

The idea is that you use POST to create a 'query' resource. Almost as if you doing a server-side prepared statement, and then later on use GET to get the result of the query.

Example of the client->server conversation:

POST /queries
Content-Type: application/json
...

A response to this might be:

HTTP/1.1 201 Created
Location: /queries/1234
Link: </queryresults/1234>; rel="some-relationship-identifier"

Then after that you could do a GET on /queries/1234 to see the query you 'prepared' and a GET on /queryresults/1234 to see the actual report.

Benefits of this is that it stays within the constraints of REST, and that you could potentially re-use queries and take a longer time to generate the results.

The obvious drawback is that it's harder to explain this to a consumer of your API, as not everyone might be familiar with this pattern and it's an extra HTTP request.

So you have to decide:

• Is it worth doing this?
• Can you encode the query in the URI instead to avoid this altogether
• Maybe you don't care enough about being RESTful and you might just want to break the rules and use POST for some complex queries.