title: REST API Design - handling resource subtypes
body: <p>In the API I'm putting together, I perform an <em>Action</em> over a set of <em>entities</em>. The issue I'm having is how to allow the action to vary depending on the client's preferences and supported methods.</p>
  
  <p>Some of the action types will need the client to provide additional options: for instance, one of the actions will result in an email being sent, so the client needs to provide the body, recipients and so on. The server may know about more action types than the client does. For instance, a new sending method could be added, but an old client isn't going to know how to set up the options for it. As well as that, there are action types that require no options from the client, and hence all clients can use that as soon as the server is enabled for it.</p>
  
  <p>As well as varying the action types based on those supported by the client/server, the entities selected also have an effect -- some entities are not valid for some action types.</p>
  
  <p>At the end of this negotiation, the client (ultimately the end user) is free to choose from any of the 'no-option' action types applicable to these entities, or any of the 'need-options' action types applicable to these entities, and supported by both the client and the server.</p>
  
  <p>Actions are triggered by setting a status field to <code>committed</code> or similar.</p>
  
  <p>My thoughts so far are to provide a generic <code>DoAction</code> resource, with a sub-collection of the entities. A property on this resource lets you specify the 'ActionType'. There is then another sub-resource called <code>ActionOptions</code> and it's this where you either set the options for the particular type you're using, or leave it empty for 'no-option' types.</p>
  
  <p>The issue I'm having is to decide if this is the best approach, or if something involving content types would be better, and also how to negotiate the list of available action types for the client, including the no-option types which the client can support even if it doesn't explicitly know about it.</p>