Correct RESTful url convention for application service calls?

Question

I saw many examples of how to structure the URL for basic CRUD operations, but I saw very little when I talked about more command operations or application service calls.

For example, let's say in my application service I have a call of type RemoveOldOrders (int customerId) that will remove any order from the system older than 2 years for the client with the identifier "customerId". What would the url look like in my calm service? What will be the payload of the call? What HTTP method (POST?) To use?

My thought: it will be something like this:

/ Customer / 1 / RemoveOldOrders as a POST, with an empty body (since the client identifier will come from the URL).

Are there any good recommendations on this?

Update: I feel that I need to clarify my question a bit instead of commenting on a possible duplicate post (yes, this post asks almost the same thing, but I really don't feel that the question was answered well).

What if I want to perform an operation against a resource, but this operation does not fit into standard HTTP verbs?

Another example: is my application connected to an ESB, and should there be a way to force the projection of my resource on the ESB to be processed? In my current SOAP-based web service, I would have a method like:

ExportCustomer(int customerId) 

Now, in the case of a RESTful service, how can I represent this action in uri? Option 1 from Brian Kelly's answer seems the most logical, something like:

 POST http://someapp/api/customer/1/export 

or will be:

 POST http://someapi/api/customer/export/1 

it's better?

Answer 1

At any time, when you want to model verbs like "delete", you should think about DELETE . Similarly, for "create" think POST (and / or possibly PUT ), for "read" think GET and for "update", think PUT (or maybe PATCH ).

So, for your “delete old orders” example, you should definitely use DELETE . Now your only remaining problem is how to identify the orders that need to be deleted. Once you figure this out, the URI scheme will fall into place.

Here are a few options:

• DELETE http://your-api.com/old-orders

  Here, the value and range of old-orders will be determined by the server receiving this request. This frees the client from having to do this, but removes their ability to change this range.

• GET http://your-api.com/order-query?days-older-than=730

  This returns a Location URI for http://your-api.com/order-query-result/{some ID} , which represents a set of old destinations. Then you can simply delete DELETE in that URI to clear old records in one fell swoop.

• Instead of making the client remember to issue removal commands of this type, suggest some configuration resource that you can control through your API to set some kind of field like purgeRecordsOlderThanDays=730 , and just let the server do this automatically for you in cron style. That would be my preferred approach.

Answer 2

For export, you need to remove the verb "export" and replace it with the ESB representation of the resource: -

• GET http://someapp/customer/{id}
• The answer includes an export link: GET http://someapp/customer/{id}/ESB
• Getting the export link returns an ESB view (with the appropriate content type)

Answer 3

For example, let's say in my application service I have a call like RemoveOldOrders (int customerId) that removes any order from a system that is older than 2 years for a client with the identifier "customerId". What would the url look like in my calm service? What would the call payload look like? What HTTP method (POST?) To use?

 RemoveOldOrders(int customerId) DELETE /oldOrders {customerId: id} DELETE /customer/{id}/orders?old=true etc... 

You should learn more about the uniform interface / resource identifiers and the HTTP method specification .

The URL really doesn't matter. It is important that you have a resource with resource identifiers (URLs), and you have to manipulate them using a single (standard) interface, for example, calling HTTP methods.