REST design: which verb and resource name to use for the filtering service

Question

I am developing a cleanup / filtering service that has a method that gets a list of objects serialized in xml and applies some filtering rules to return a subset of these objects.

• In the REST-ful service, which verb should I use for such a method? I thought GET was a natural choice, but I have to put serial XML in the body of the request, which works, but feels incorrect. Other verbs do not seem to correspond semantically.

• What is a good way to define this service interface? Resource naming / Purge or / Filter seems strange mainly because in the examples that I see on the Internet, it is always a name and not a verb used for the name of the resource.

• I correctly feel that REST services are better suited for CRUD operations, and you start to bend rules in situations like this service? If so, will I make the wrong architectural choice.

• I tried to develop this REST-ful service (as opposed to SOAP) for simplicity, but such inconvenient cases happen a lot and make me feel like I'm missing something. Either choosing REST, where you can’t use it, or maybe you are thinking too much about some things that really don't matter? In this case, what is really important?

Answer 1

REST uses HTTP the way it was designed. To consider RESTful (the name was REST design :):

• URLs should be permalinks to the resource (benefits of caching, saving / splitting endpoints, etc.).
• Since they are permanent links to the resource, the presence of verbs in the URL is a hint that you are mistaken (a filter is a verb).
• The resource set may be the endpoint / foos.
• If you want to filter a collection of resources, consider the querystring options, for example: filter = or something like that? ids = 1,2,3,4,5.
• GET must not modify resources. Note that “cleanup” implies deletion, so be careful when changing resources when you perform a GET. REST says that GET should not modify resources. Imagine that the cache server accepts your cleanup request as GET and returns OK because t is cached. Caching servers know not to cache POST, DELETE, etc. (What a method was developed by HTTP).
• Do not rule out multiple calls — for example, you can filter and get a set of resources for cleaning, and then you can make many or one DELETE calls to perform the cleaning.
• Sometimes there is a temporary resource, such as a transaction or “work,” which can work as a cleanup. Do not exclude POST for the resource with the body containing the elements to clear, and it returns the identifier of the job. You can then request a job to perform a cleanup or condition.

It’s hard to give an exact guide because the question is not clear, but hopefully the guidance and advice of RESTful overseers have set you on the right track. If you clarify the exact calls, I will try and recommend the API.

So let's say you wanted to clear duplicate foos.

[GET] / foos / duplicates (or / foos? Filter = duplicates)

returns a body with foos identifiers that are duplicates. Let's say it returns 1,2,5 (there may be names).

Then you can specify:

[DELETE] / foos with a body that contains an array containing 1,2,5 (or names if they are unique). the delete call is passive, so even if the GET call is cached according to REST principles, that’s good.

It is also possible and important not to switch to a REST route, such as POX or JOSN RPC via http, but simply to understand at this point that it is not REST. And this is fine, but you do not get the benefits of REST described in the abstract.

http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

Also read the following:

http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http

EDIT:

After reading the comment in which you explained, you send the server a set of objects (not supported on the server side), and it returns a subset with filtered workarounds (for example, a helper function on the server side), some parameters:

• If possible, do this client / browser side - why accept network feedback in order to filter out cheats from the collection?
• If for some reason only the server has certain knowledge / data to determine that the two elements are functional equivalents (although the data is not exactly the same), then consider POSTing the data set to the server with the response body containing a unique / filtered set. Even though the server does not support dialing, it will fall into a “temporary” object or install, and the server will modify it. This is not a conceptual GET of server resources and caching does not provide benefits in this scenario.

Answer 2

The last question: what is really important is to make the work in such a way that it

• Right
• How easy to use as practical
• Easily supported by future programmers (maybe includes you)

REST is a natural help for resource operations, where each URL corresponds to some object that can be manipulated. This is less natural for other purposes, but more recommendations than the actual rules . Others pointed out the original dissertation on REST , but it is worth remembering that several implementations are clean.

If you have multiple URLs that perform these conversion functions, consider placing them in your own URL, for example /api/filter and /api/transliterate , etc. This will help users and accompanying users know that certain URLs aren't REST, but are more like remote procedure calls. Posting data to these URLs will return some data.

If you are stuck on certain names, you should make a list of candidates, have several beers, and then choose one from the list. This is what I do when I get hung up on the little things.

SOAP is a neat protocol and has its uses, but it tends to be very difficult. Good documentation and consistency are probably more important to your beginner API than using any particular technology.