title: Modeling Version Control Operations in REST
body: <p>We have recently added version control capabilities to our system, we are having hard time modeling these capabilities in a RESTful way. </p>
  
  <p>The system works as follows, when it's configured in "version-control" mode,  before making modification to an entity one must check it out first (a private copy is created for that user). After modifying the local copy the user can then check it in to commit the changes or undo the check out to discard the changes.</p>
  
  <p>We are debating what is the right approach to model the "check-in", "check-out", "get-version" and "undo check-out" operations.</p>
  
  <p>so lets say we have a resource (named my-resource)</p>
  
  <pre><code>  http://my-system/my-resources/{id}
  </code></pre>
  
  <p>and we want to add version control capabilities on top of it, we are arguing between the two following approaches:</p>
  
  <ol>
  <li><p>Operation oriented</p>
  
  <p><strong>Check In:</strong>  POST on <a href="http://my-system/my-resources/" rel="nofollow noreferrer">http://my-system/my-resources/</a>{id}/check-in</p>
  
  <p><strong>Check-Out:</strong> POST on <a href="http://my-system/my-resources/" rel="nofollow noreferrer">http://my-system/my-resources/</a>{id}/check-out</p>
  
  <p><strong>Get Version:</strong> GET <a href="http://my-system/my-resources/" rel="nofollow noreferrer">http://my-system/my-resources/</a>{id}/versions/{version-id}</p>
  
  <p><strong>Undo Check-Out</strong>: POST on <a href="http://my-system/my-resources/" rel="nofollow noreferrer">http://my-system/my-resources/</a>{id}/undo-check-out</p></li>
  <li><p>Resource Oriented</p>
  
  <p><strong>Check In:</strong>  POST on <a href="http://my-system/my-resources/" rel="nofollow noreferrer">http://my-system/my-resources/</a>{id}/versions </p>
  
  <p><strong>Check-Out:</strong> POST on <a href="http://my-system/my-resources/" rel="nofollow noreferrer">http://my-system/my-resources/</a>{id}/check-out</p>
  
  <p><strong>Get Version:</strong> GET <a href="http://my-system/my-resources/" rel="nofollow noreferrer">http://my-system/my-resources/</a>{id}/versions/{version-id}</p>
  
  <p><strong>Undo Check-Out</strong>: DELETE on <a href="http://my-system/my-resources/" rel="nofollow noreferrer">http://my-system/my-resources/</a>{id}/check-out</p></li>
  </ol>
  
  <p>What do you think? 
  Do you have a suggestion how to model these operations? 
  Are you familiar with similar public APIs to consult with?</p>