0

I'm implementing a RESTful API for a DVD rental website using ASP.NET Web API. The domain model (simplified) consists of Customer and Subscription entities. A customer has an associated subscription.

Most of the operations exposed by the API are simple CRUD operations, which are easy enough to model according to RESTful principles. E.g. 

GET /api/subscriptions/1 - get subscription with id 1
POST /api/subscriptions - add a new subscription
PUT /api/customers/2 - update customer with id 2 with contents of PUT body

There is a requirement to periodically check for expired subscriptions, by comparing the EndDate field on each Subscription entity read from our database with the current date. For each subscription that has expired, the CustomerStatus field of the associated customer should be set to Archived and an email sent to the customer. The operation will be exposed through our REST API and invoked daily from an external service.

What URL scheme should I use to expose this operation according to RESTful principles? My first thought is that it's a PUT operation on api/customers/{SomeResource} as it potentially involves updating the CustomerStatus field of zero or more customers and is also an idempotent operation.

For example:

PUT /api/customers/expired

Does this sound reasonable?

Note that there is no body sent in this request, as the customers whose statues are being updated are queried from a database rather than being supplied by the end user. My understanding is that a PUT request doesn't have to include a body.

aw1975
  • 1,669
  • 3
  • 20
  • 35

1 Answers1

2

This is almost certainly a POST operation.

However, I question the design of your service. Why does the behaviour you describe need to be externally-controlled by way of a RESTful API? If the exact timing and nature of the operation is known beforehand, why not use some other means of scheduling the job...a means that is more straightforward and wouldn't raise these kinds of questions?

Ref: Stack Overflow

Edit: note that the operation described by the OP is not idempotent and thus not a qualifying PUT operation.

Additional edit: note that the .Net framework uses the POST method by default for service endpoints marked with the WebInvoke attribute. Per the documentation for this attribute, it represents an endpoint that "is logically an invoke operation". To me, this reads like a remote procedure call (i.e. RPC).

Community
  • 1
  • 1
Dan Forbes
  • 2,734
  • 3
  • 30
  • 60
  • Even if it's not known beforehand, it would be better to expose a resource that lets clients control the schedule than to have them POST directly to execute the operation. The POST leaves you vulnerable to network issues and other external failures. – Eric Stein Jun 20 '16 at 18:33
  • I totally agree, exposing this kind of operation is not only inefficient but also insecure. Your operation is clearly schedulable and should be handled entirely from behind the boundaries of your application. – Federico Dipuma Jun 20 '16 at 20:29
  • By handling the scheduling from behind the application boundary, are you suggesting that it runs as a background job from within the web process? I had considered this, and although there are frameworks such as Hangfire that facilitate this, it's can be problematic to run background tasks this way. As the application will be hosted in Azure, the intention is to schedule an Azure WebJob to periodically invoke the API endpoint, which will be secured using OAuth2. – aw1975 Jun 20 '16 at 21:33
  • However agree that it should be a POST operation. – aw1975 Jun 20 '16 at 21:39
  • Fair enough, @aw1975! If you agree that this is the correct answer, please consider officially "Accepting" it. Thanks! – Dan Forbes Jun 21 '16 at 13:23