So, I was looking through some articles on creating REST API’s.
And some of them suggest using all types of HTTP requests: like PUT
DELETE
POST
GET
.
We would create for example index.php and write API this way:
$method = $_SERVER['REQUEST_METHOD']; $request = split("/", substr(@$_SERVER['PATH_INFO'], 1)); switch ($method) { case 'PUT': ....some put action.... break; case 'POST': ....some post action.... break; case 'GET': ....some get action.... break; case 'DELETE': ....some delete action.... break; }
OK, granted – I don’t know much about web services (yet).
But, wouldn’t it be easier to just accept JSON object through regular POST
or GET
(that would contain method name and all parameters) and then respond in JSON as well. We can easily serialize/deserialize via PHP’s json_encode()
and json_decode()
and do whatever we want with that data without having to deal with different HTTP request methods.
Am I missing something?
UPDATE 1:
Ok – after digging through various API’s and learning a lot about XML-RPC, JSON-RPC, SOAP, REST I came to a conclusion that this type of API is sound. Actually stack exchange is pretty much using this approach on their sites and I do think that these people know what they are doing Stack Exchange API.
Advertisement
Answer
The idea of REpresentational State Transfer is not about accessing data in the simplest way possible.
You suggested using post requests to access JSON, which is a perfectly valid way to access/manipulate data.
REST is a methodology for meaningful access of data. When you see a request in REST, it should immediately be apparant what is happening with the data.
For example:
GET: /cars/make/chevrolet
is likely going to return a list of chevy cars. A good REST api might even incorporate some output options in the querystring like ?output=json
or ?output=html
which would allow the accessor to decide what format the information should be encoded in.
After a bit of thinking about how to reasonably incorporate data typing into a REST API, I’ve concluded that the best way to specify the type of data explicitly would be via the already existing file extension such as .js
, .json
, .html
, or .xml
. A missing file extension would default to whatever format is default (such as JSON); a file extension that’s not supported could return a 501 Not Implemented
status code.
Another example:
POST: /cars/ { make:chevrolet, model:malibu, colors:[red, green, blue, grey] }
is likely going to create a new chevy malibu in the db with the associated colors. I say likely as the REST api does not need to be directly related to the database structure. It is just a masking interface so that the true data is protected (think of it like accessors and mutators for a database structure).
Now we need to move onto the issue of idempotence. Usually REST implements CRUD over HTTP. HTTP uses GET
, PUT
, POST
and DELETE
for the requests.
A very simplistic implementation of REST could use the following CRUD mapping:
Create -> Post Read -> Get Update -> Put Delete -> Delete
There is an issue with this implementation: Post is defined as a non-idempotent method. This means that subsequent calls of the same Post method will result in different server states. Get, Put, and Delete, are idempotent; which means that calling them multiple times should result in an identical server state.
This means that a request such as:
Delete: /cars/oldest
could actually be implemented as:
Post: /cars/oldest?action=delete
Whereas
Delete: /cars/id/123456
will result in the same server state if you call it once, or if you call it 1000 times.
A better way of handling the removal of the oldest
item would be to request:
Get: /cars/oldest
and use the ID
from the resulting data to make a delete
request:
Delete: /cars/id/[oldest id]
An issue with this method would be if another /cars
item was added between when /oldest
was requested and when the delete
was issued.