Comment by JimDabell

It's pretty simple – the information a client needs to transition from one state to another needs to be encoded in the documents. So if you were to design a garage door opener, a non-REST specification might say something like:

    To get the door status, GET https://example.com/status  
    
    To open the door, POST to https://example.com/open  
    
    To close the door, POST to https://example.com/close

A REST approach might use a document something like this:

    {
        "doorState": "closed",
        "actions": [
            {
                "label": "Open the door",
                "href": "/open",
                "method": "POST"
            }
        ]
    }

Then, upon a client performing an "Open the door" action, the server would then respond with a document like this:

    {
        "doorState": "open",
        "actions": [
            {
                "label": "Close the door",
                "href": "/close",
                "method": "POST"
            }
        ]
    }

…and vice-versa. So at any given point, the web service is describing to the client what the state is and how to transition to other states. There's quite a few different benefits to doing it this way – for instance, if you wanted to add a "Turn the garage light on" feature, you could just add the action into the API and clients would be able to use it without any changes whatsoever. Or if you wanted to disable an action, you'd simply remove it from the actions array and the client wouldn't present it to the user as an option. Want to A/B test different label text? You don't need any special A/B testing functionality in the client, just vary the responses you send to users and observe which actions they take. Want to translate into different languages? Just take a look at the Accept-Language header coming from the client and respond with the right label text.

In practice, you'd want to use a vocabulary that's already out there like Hydra instead of coming up with your own format. But it can sometimes take a little time to get up to speed with them because they are necessarily quite flexible. But you can get most of the way there by simply thinking about it in terms of "the server tells the client what to do and how to do it".

For something as simple as a garage door that you are certain will never need to change? The benefits REST brings probably aren't going to be worth much to you. But as the complexity of an API grows, the point at which it's easier to use REST than not arrives very quickly.

If you want to read more about this, the best book I've found on the subject is RESTful Web APIs: http://restfulwebapis.com/