Correct headers for PHP RESTful Application?

Question

Goal: A RESTful API
Question: Is the method I have below a true RESTful API or is it missing something like I was told?
This is a 3 part question..

Let's assume I have a PHP project that has an API that returns data in either XML or JSON formats, you would access the API like this below...

server.com/article/123 | Returns ID 123 using GET
server.com/article/new | Creates a new article using POST
server.com/article/123/edit | Edits an article with the ID 123 using POST
server.com/article/123/delete | Deletes article with ID 123 using POST

1)
I always read also that PUT should be used for editing objects, below I put the word POST as the user would send a POST to tht URI for the delete action, should I be using PUT in php by using something like this instead?

$_PUT  = array();  
if($_SERVER['REQUEST_METHOD'] == 'PUT') {  
    parse_str(file_get_contents('php://input'), $_PUT);  
}

2)
I was told in a question I wrote on SO a while back that this is similar to a RESTful API but that it is not, the answer I got was this...

In short, your service is not RESTful, but it is close. Rather than specify actions (edit, delete, ...) in URL segments, you will want to make use of HTTP verbs (GET, PUT, POST, DELETE).

Either the guy did not know what he was talking about or I just DO NOT GET IT, after reading countless articles on the subject, and comparing with every API I can find, how is my example above NOT RESTful?

I would like to make a RESTful API, please help me correct my example above if needed?

3)
Also assuming I plan returning a JSON response to the user with something like this...

<?php
header('HTTP/1.1 200 OK');  
header('Content-type: application/json');

$data = // my code that returns the appropriate data;

echo json_encode($data);
?>

Is that the correct way of returning the result to a user or am I missing something? Many articles and questions talk about the concept but don't get into the actual code like my examples.

Answer 1

To address part 2 of your question, a more RESTful URL and method structure would be as follows:

• server.com/articles/123 – GET: return the article
• server.com/articles/123 – PUT: replace the article with the one in the request body
• server.com/articles/123 – DELETE: delete the article
• server.com/articles/ – POST: create a new article

The idea here is that the URL represents the resource itself (in this case, the article) and the verb, where practical, indicates what you want to do to it. The best example I can think of in the wild of a true RESTful API is the latest version of the GitHub API: as far as I have seen, they use HTTP methods, response codes and custom MIME types appropriately.

In answer to part 3 of your question, that is certainly a valid way to do it, but if you were to use a custom MIME type such as application/vnd.myawesomesite.article+json, that would make it easier to interpret at the client’s end, as the client could use the MIME type to determine how to parse the result: for instance, the client could dispatch to different deserialisers and classes depending on the MIME type presented. Again, the folks at GitHub give some examples in their API docs.

Answer 2

1. You should be able to use $_POST on a PUT request, as long as the request includes a the proper Content-Type header. It's a generic superglobal that should always be filled when there is a HTTP body sent and the correct Content-Type header is used. In fact, it could even appear on a broken GET request.
2. Your URLs could be more RESTful. For example, server.com/article/123 could house not only GET, but also POST (edit) and DELETE (delete). There's no need to use separate URLs if you're already using different request methods.
3. RESTful primarily describes the way of communicating between the client and the server, not how it does that. I haven't seen the 201 header used much in the past - usually a 200 OK is good enough. Of course, nothing should stop you from using the 201 code.

#protip: wrap all your data in a result object, like {'success':true,'result':<the result>,'resulttype':'article'}. Developers using your API (if you publish one) will find this helpful. For you this means that you can add extra information to the response easily.

Very interesting article on FourSquare's REST API