title: Understanding REST: Verbs, error codes, and authentication
body: <p>I am looking for a way to wrap APIs around default functions in my PHP-based web applications, databases and CMSs. </p>
  
  <p>I have looked around and found several "skeleton" frameworks. In addition to the answers in my question, there is <a href="http://tonic.sourceforge.net/" rel="noreferrer">Tonic</a>, a REST framework I like because it is very lightweight.</p>
  
  <p>I like REST the best for its simplicity, and would like to create an API architecture based on it. I'm trying to get my head around the basic principles and have not fully understood it yet. Therefore, a number of questions.</p>
  
  <p><strong>1. Am I understanding it right?</strong></p>
  
  <p>Say I have a resource "users". I could set up a number of URIs like so:</p>
  
  <pre><code>/api/users     when called with GET, lists users
  /api/users     when called with POST, creates user record
  /api/users/1   when called with GET, shows user record
                 when called with PUT, updates user record
                 when called with DELETE, deletes user record
  </code></pre>
  
  <p>is this a correct representation of a RESTful architecture so far?</p>
  
  <p><strong>2. I need more verbs</strong></p>
  
  <p>Create, Update and Delete may be enough in theory, but in practice I will have the need for a lot more verbs. I realize these are things that <em>could</em> be embedded in an update request, but they are specific actions that can have specific return codes and I wouldn't want to throw them all into one action.</p>
  
  <p>Some that come to mind in the user example are:</p>
  
  <pre><code>activate_login
  deactivate_login
  change_password
  add_credit
  </code></pre>
  
  <p>how would I express actions such as those in a RESTful URL architecture?</p>
  
  <p>My instinct would be to do a GET call to a URL like </p>
  
  <pre><code>/api/users/1/activate_login 
  </code></pre>
  
  <p>and expect a status code back. </p>
  
  <p>That deviates from the idea of using HTTP verbs, though. What do you think?</p>
  
  <p><strong>3. How to return error messages and codes</strong></p>
  
  <p>A great part of REST's beauty stems from its use of standard HTTP methods. On an error, I emit a header with a 3xx,4xx or 5xx error status code. For a detailed error description, I can use the body (right?). So far so good. But what would be the way to transmit a <strong>proprietary error code</strong> that is more detailed in describing what went wrong (e.g. "failed to connect to database", or "database login wrong")? If I put it into the body along with the message, I have to parse it out afterwards. Is there a standard header for this kind of thing?</p>
  
  <p><strong>4. How to do authentication</strong></p>
  
  <ul>
  <li>What would a API key based authentication following REST principles look like?</li>
  <li>Are there strong points against using sessions when authenticating a REST client, other than that it's a blatant violation of the REST principle? :) (only half kidding here, session based authentication would play well with my existing infrastructure.)</li>
  </ul>