Web API - REST帮助和澄清

Question

I'm writing an API using WebAPI, and whilst I'm designing this from scratch, I'm trying to make it RESTful. In the past when doing web service work, I've always used RPC patterns (ASMX, SOAP, etc) - eg. using an arbitrary method name that matches what I want it to do. To me this seems much more intuitive and explicit than REST, but given WebApi seems to be more RESTful by nature (I know you can change the route so it's not), I've decided to try and make it RESTful.

I understand (I think!) the basics - eg. POST for create, PUT for update when specifying an ID, GET to get, DELETE to delete, etc, etc.

My confusion is how to deal with returning collections vs a single object. For example, say that I've got an API controller called UsersController . As far as I gather, I'd have the following URLs:

GET: /api/users (lists all users)
GET: /api/users/1 (lists details about user with ID 1)
POST: /api/users (creates a new user with details sent in the POST data)
PUT: /api/users/1 (updates the existing user with ID 1 with details sent in the POST data)
DELETE: /api/users/1 (deletes the existing user with ID 1)

For the first URL above, I need to also send various filter/search criteria. Does this criteria just get passed through as query string parameters? Or should I be using a completely different controller for this "search" functionality? Eg. UserSearchController? If so, should that be a POST in this case or still a GET? Actually as I write this, I'm wondering whether a separate controller makes sense anyway, as I'll probably want more detail returned in the GET for a single user than in the search results. Does it make it not RESTful if the same controller does return different data for a single object GET vs a GET returning a collection?

Answer 1

For the first URL above, I need to also send various filter/search criteria. Does this criteria just get passed through as query string parameters?

It definitely makes sense to use query string for specifying filter/search parameters.

should I be using a completely different controller for this "search" functionality? Eg. UserSearchController?

You should not do that. There are couple of reasons that i see here:

1. There will be almost identical functionality in GET: /api/users

2. You can easily implement GET: /api/users , GET: /api/users?filter=...&sort=... and GET: /api/users/1 in one method:

    //If you are using EF it could look like //filter and sort arguments could be added here as well public HttpResponseMessage Get(int? id) { if(id.HasValue) { return Request.CreateResponse( HttpStatusCode.OK, Context.Users.SingleOrDefault<Users>(u => u.Id == id)); } var users = Context.Users.Select(apply filter).OrderBy(apply sort).ToList(); return Request.CreateResponse(HttpStatusCode.OK, users); } 

You can take a look at OData - it may help you with the implementation.

3. Spreading this logic between different controllers compromises single responsibility principle - your users controller should handle all the logic related to users and only this logic

If so, should that be a POST in this case or still a GET?

If you want to make your API RESTful you should be using GET. BUT you should be aware, that returning an array of JSON objects through GET could be potentially vulnerable to JSON hijacking . One of the simplest solutions to this exploit is allowing to get JSON arrays through POST only (there are other solutions as well).

I'll probably want more detail returned in the GET for a single user than in the search results. Does it make it not RESTful if the same controller does return different data for a single object GET vs a GET returning a collection?

This is totally fine to return more details for a single object than for a collection. It doesn't affect RESTfulness of your API in any way.

COMMENT

You wrote:

PUT for update when specifying an ID

Actually it is not entirely correct:

• PUT should be used for complete replacement of the entire entity
• PATCH should be used to perform a partial update.

Answer 2

If you want to get passed through criteria as query string parameters to URI, you can do that using Attribute Routing into WebApi. I think attribute-routing-in-web-api helps to you.

Answer 3

Yes, I would pass filter parameters as query string options. The 'restfulness' of your application is not dependent on controller structure, so you can follow a structure that best suits your application