Understand Rest through an example

Question

I am developing a client - server web service. The front end is build with html/javascript/jquery/jqm and the back end with php/mysql.

When the client starts it has a static id(never changes) and a dynamic-token(that means it may or may not change). For this reason every time the client starts we register him to our server we make a POST request to our server where in the body we have a JSON file with the id and token. The post request is made to a php script that looks like this : myserver.com/register.php , The php script takes the id and token and makes a query to the database to see if they exist. If the id doesnt exist it creates a new record. If it exists , it checks if the token has been changed so it updates.

From the client the user can subscribe to a number of events (lets say 10). The events are presented in a list with checkboxes. The user checks the events that he wishes to subscribe and presses a subscribe button. When the subscribe button is hit , a POST request is made to a php script that in the body has a json file with the id of the user and all the names of the events with a boolean (subscribe or not subsribe) eg

id: xxxxxx
event1: 1
event2: 0
event3: 0
event4: 1
...

The php script looks like this : myServer/subscribe.php. When the the request arrives the php file reads the JSON that was received. He searches for the id in the database and then he checks the names of the events and the booleans that were sent. If it is 1 he subscribes the user. If is 0 he unsubscribe the user. If the user was already subscribed and he subscribes again nothing happens. Same for the unsubscription.

Finally , when the user enters the subscription page , a POST request is made to the server with a JSON file in the body that has the id of the user. The request is made on a php file that looks like myServer/whereSubsribed.php. This php file , gets the id and looks in the database in which events this id is subscribed to. When it finishes it responds(makes an echo) to the client with a json file that has all the events that the user is already subscribed , so that when the checkboxes are loaded , the events in which the user is already subscribed can seem checked.

Is the above service Rest ? I have a really really hard time to understand what is Rest and what is not. What i understand:

I know that i should use POST PUT DELELE GET but i can do everything with just POST as u saw. Then why use them? I know that Rest is about nouns and not verbs , is about resources and not actions. I have NO idea what this means IN PRACTICE.

Can someone please , in this specific case that i describe , give a description of how a Rest web service would look like? How is it possible that i dont have actions like subscribe/unsubscribe/register ?

I hope that by giving me an example i can finally understand what is Rest. At this point maybe i should say that i dont know what is SOAP either. When i started developing my service i just made it like this because thats what i thought is the correct way. Then i learned about the Rest/Soap thing. So is Rest another way that my service could be done and if yes please take some time and explain me how?

Thank you very very much for reading this long post.

**If you are kind enough to give me an answer , please dont give me a definiton or a theorytical approach on the subject. I ve read almost everything that needs to be read. I am also a new html/php scripter , so i would appreciate if you could give me an example with the exact same service that i described. How it would look if it was to be Restful would be great to understand i think.

EDIT

The way i see it , i used HTTP requests (POST) to push some data (id , token , etc) to a specific action/php script(subscribe , register , whereSubscribed).

Rest should be the exact oposite? Send actions through HTTP (post put delete update) to a resource(a user an event).

Does that mean that all the programming would change too? I dont understand how it would be possible to not have the scripts that i wrote. How can a subscription be made programaticaly when you dont have the php script to do so?!

There great explanation of REST best practices: http://www.slideshare.net/landlessness/teach-a-dog-to-rest http://vimeo.com/17785736 — Stanislav Terletskyi, Jun 20 '13 at 16:16
See here as well: http://stackoverflow.com/questions/2750659/understanding-rest-through-an-example — adamdehaven, Jun 20 '13 at 16:20

score 1 · Accepted Answer · answered Jun 20 '13 at 16:17

As you've described it, no it's not REST. In REST, a URL is like an address that points to a resource. In effect, the URLs are the nouns and the HTTP methods are the verbs.

Your system as described has scripts which are verbs. For example, the subscribe.php carries out the action of doing something.

Thinking RESTfully, your resources include things like tokens and subscriptions. If you wanted to do REST, each subscription should have a clear and unambiguous URL.

For example, a subscription's URL might be /path/to/subscriptions/<subscription_id> where <subscription_id> is replaced with the specific ID of the subscription in question. When the client wants to subscribe to something, they'd PUT something to that URL.

If a client wanted to make a subscription, but didn't know the exact final location, they'd POST to something generic like /path/to/subscriptions and the HTTP response would include a Location header pointing the way to the correct /path/to/subscriptions/<subscription_id>.

PHP is not immediately conducive to RESTful programming. A PHP script lives at a particular path and carries out an operation (verb). You have to go out of your way to have pretty URLs that reflect the noun-ness of resources.

Hope this helps!

I understand very well what you are saying in your first 3 paragraphs. I also completely agree with ur last paragraph that PHP lives in a particular path and carries out an operation => VERB! You say that a subscriptions URL should look like /path/to/subscriptions/ . But what is behind that URL? Is again a php script that makes the subscription right? I am sure that Rest is not about pretty URL names that look like nouns or verbs. So even the way you describe it , under these URLS wouldnt you execute the same code that i execute? — Johny Jaz, Jun 20 '13 at 16:24
REST doesn't care about how it's implemented - the "behind" you refer to. It care's about the response. So what do you receive when you GET /path/to/subscriptions/X? REST would say you receive a representation of the resource subscriptions/X. What happens when you PUT to subscriptions/X? REST would say you overwrite subscriptions/X with the body of the HTTP request. Think of the URL as a filename. What happens when you write to the file? The answer is you don't care what the OS does, as longas it overwrites what's there with what you supplied - that's PUT. — jimbo, Jun 20 '13 at 16:53
Yes but again this is in theory. What i am asking is in practice what happens :p What is behind these urls if not my scripts? Thats what i cant understand. — Johny Jaz, Jun 20 '13 at 17:07

score 1 · Answer 2 · edited May 23 '17 at 12:19

You are exactly right, in your comment to the previous answer :

I am sure that Rest is not about pretty URL names that look like nouns or verbs.

RESTfull means using the full potential of HTTP like was mentioned and explained through a nice example in the below post :

For example. Let's imagine that we have a user database that is managed by a web service. Using the non-restful approach it would probably look something like this:

/user_create
/user?id=xxx
/user_edit?id=xxx
/user_delete?id=xxx

/user 
/user/xxx

If you want to create a new user you simply send a POST request to that URL with the data you want to create. If you want to retrieve a user you send a GET request to /user/xxx. If you want to update a user you simply send the fields you want to update using a PUT request to /user/xxx. If you want to delete it, you send a DELETE request instead.

An even more concrete example. In a RESTful application you'll never modify data using a GET request. This is what PUT, POST and DELETE are for. Most web applications do this all the time, though, and are therefore not RESTful.

Taken from : What exactly is RESTful programming?

With that being sad, RESTfull means using all the below operations correctly: http://en.wikipedia.org/wiki/Http_protocol#Request_methods

enter image description here

This is also a nice post that answers many questions about REST Apis:

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Ok i understand the concept. That we send the action with the request and we point at the resource(url). For example you say if you want to update a user make a PUT request to /user/xxx. This is what i dont understand. What is under the /user/xxx ?? in my case i had a script eg /user/subscribe.php that takes as input the id and does what it does. In what you describe what is this link? Is a method inside a php script? Is a class? Is an actual php file? — Johny Jaz, Jun 20 '13 at 16:54
it could be php script (zend framework or regular php) it could be a CGI script, anything on the server side. — Mehdi Karamosly, Jun 20 '13 at 17:09
I ve never used a framework. Do you think that by using a framework these things will come easier to understand for me? Does the framework provide solutions for this? — Johny Jaz, Jun 20 '13 at 17:13
it is not required that you use a framework, you can use simple php, however I am sure that you will love using frameworks, specially MVC frameworks like Zend MVC framework (they seperate between the Model (data), Vue (HTML template/ css) and Conrtoller (server computation-operations) they are scallable and easier to maintain. — Mehdi Karamosly, Jun 20 '13 at 17:24

Understand Rest through an example

EDIT

2 Answers2