title: designing actions in REST API - when is RESTful too RESTful?
body: <p>I am in the process of designing a REST API for a project we are working on. That is, I am writing the specifications which will be implemented later on.</p>
  
  <p>I am having troubles to think into <em>nouns/resources</em> instead of <em>actions/verbs</em>. Without going into too much project specifics, we are writing an API around SVN. For example, take the action which commits changes to the SVN server. In our project, we have multiple definitions/versions of the commit action:</p>
  
  <ul>
  <li>simply commit all changed files</li>
  <li>commit a list of changed files (a subset, instead of the whole set of changed files)</li>
  <li>...</li>
  </ul>
  
  <p>(1) How would you design the URL? The first question is, how do I describe the <em>commit action</em> as a <em>noun/resource</em> instead of a <em>verb</em>?</p>
  
  <p>Some would say:</p>
  
  <pre><code>POST/PUT http://server.com/api/revision/commit
  </code></pre>
  
  <p>Should it be a POST or a PUT? I am not really creating a <em>commit resource</em>, so it's not a POST. However, I am not really changing a <em>commit resource</em>, so it's not a PUT. Actually, it's not a <em>resource</em>, it's an <em>action</em>. Once the action is executed, it's gone, there is no resource to be created, changed or kept for later reference.</p>
  
  <p>That said, it must be a resource, so the URL should probably be like this</p>
  
  <pre><code>POST http://server.com/api/revision/commitment
  </code></pre>
  
  <p>It's also a POST, since we are creating a commitment. We are not changing anything, so no PUT. Also note that I changed <em>commit</em> into <em>commitment</em>, to reflect the fact that we are dealing with resources.</p>
  
  <p>Does this make sense? To me it doesn't, it drives me nuts. I want to execute an action, not create a resource which resembles the action. But anyway.</p>
  
  <p>That said, going further, I just created a commitment resource. So logically, I should be able to retrieve it later on:</p>
  
  <pre><code>GET http://server.com/api/revision/commitment/:id
  </code></pre>
  
  <p>But there is no commitment resource! I was forced to make one in order to be RESTful. <strong>head explodes</strong></p>
  
  <p>So, how do you really specify actions on resources in a REST API? I am not talking about the kind of actions which create a resource (create user, ...), but about the kind of actions which manipulate a resource or act on a resource (commit revision, ...).</p>
  
  <p>(2) Then, secondly, in case of the second definition (see above), how do we specify the subset of changed files? Through parameters or in some structure (for example JSON array) in the BODY? Which one is preferred? Are there any general rules?</p>
  
  <p>Thanks all!</p>