Flag of Ukraine
SymfonyCasts stands united with the people of Ukraine
This course is archived!
This tutorial uses a deprecated micro-framework called Silex. The fundamentals of REST are still ? valid, but the code we use can't be used in a real application.

REST: Resources and Representations

Video not working?

It looks like your browser may not support the H264 codec. If you're using Linux, try a different browser or try installing the gstreamer0.10-ffmpeg gstreamer0.10-plugins-good packages.

Thanks! This saves us from needing to use Flash or encode videos in multiple formats. And that let's us get back to making more videos :). But as always, please feel free to message us.

REST: Resources and Representations

REST: Representational state transfer. The term was coined famously by Roy Fielding in his doctoral dissertation in 2000. It’s complex, and a lot of what makes a REST API hard is understanding and debating the many rules, or constraints laid out in his document.

When you think about an API, it’s pretty common to think about its endpoints, in other words the URLs. With REST, if you have a URL, then you have a resource. So, /programmers/Namespacinator is probably the address to a single programmer resource and /programmers is probably the address to a collection resource of programmers. So even a collection of programmers is considered one resource.

But we already build URLs that work like this on the web, so this is nothing new.


Now that you understand resources, I want to think about representations. Suppose a client makes a GET request to /programmers/Namespacinator and gets back this JSON response:

    "nickname": "Namespacinator",
    "powerLevel": 5

That’s the programmer resource, right? Wrong! No!

This is just a representation of the programmer resource. It happens to be in JSON, but the server could have represented the programmer in other ways, like in XML, HTML or even in JSON with a different format.

The same applies when a client sends a request that contains programmer data:

POST /api/programmers HTTP/1.1
Host: CodeBattles.io
Authorization: Bearer b2gG66D1Tx6d89f3bM6oacHLPSz55j19DEC83x3GkY
Content-Type: application/json

    "nickname": "Namespacinator"

The client doesn’t send a programmer resource, it just sends a representation. The server’s job is to interpret this representation and update the resource.

Representation State

This is exactly how browsing the web works. An HTML page is not a resource, it’s just one representation. And when we submit a form, we’re just sending a different representation back to the server

One resource could have many representations. Heck, you could get crazy and have an API where you’re able to request the XML, JSON or HTML representations of any resource. We’re just crazy enough that we’ll do some of that.

A representation is a machine readable explanation of the current state of a resource.

Yes, I said the current “state” of the resource, and that’s another important and confusing term. What REST calls state, you probably think of as simply the “data” of a resource. When the client makes a GET request to /programmer/Namespacinator, the JSON is a representation of its current state, or current data. And if the client makes a request to update that programmer, the client is said to be sending a representation in order to update the “state” of the resource.

In REST-speak, a client and server exchange representations of a resource, which reflect its current state or its desired state. REST, or Representational state transfer, is a way for two machines to transfer the state of a resource via representations.

I know I know. We just took an easy idea and made it insane! But if you can understand this way of thinking, a lot of what you read about REST will start to make sense.

Leave a comment!

Login or Register to join the conversation
Default user avatar
Default user avatar yadameda | posted 2 years ago

Simple great explanation!

2 Reply
Default user avatar

Thanks for this wonderful video that completely demystified resource vs. representation vs. state for me.

1 Reply
Default user avatar
Default user avatar roberto_001 | posted 1 year ago

thank you, great explanation!


Hey Roberto!

Thank you for your feedback! That's what we're trying to do all the time at SymfonyCasts - explain complex things simple, and we're really happy to hear the explanation was clear for you in this video!


1 Reply
Aristotele T. Avatar
Aristotele T. Avatar Aristotele T. | posted 3 years ago

Best explanation found on REST, congratz!

Cat in space

"Houston: no signs of life"
Start the conversation!

This tutorial uses a deprecated micro-framework called Silex. The fundamentals of REST are still ? valid, but the code we use can't be used in a real application.

What PHP libraries does this tutorial use?

// composer.json
    "require": {
        "silex/silex": "~1.0", // v1.3.2
        "symfony/twig-bridge": "~2.1", // v2.7.3
        "symfony/security": "~2.4", // v2.7.3
        "doctrine/dbal": "^2.5.4", // v2.5.4
        "monolog/monolog": "~1.7.0", // 1.7.0
        "symfony/validator": "~2.4", // v2.7.3
        "symfony/expression-language": "~2.4" // v2.7.3
    "require-dev": {
        "behat/mink": "~1.5", // v1.5.0
        "behat/mink-goutte-driver": "~1.0.9", // v1.0.9
        "behat/mink-selenium2-driver": "~1.1.1", // v1.1.1
        "behat/behat": "~2.5", // v2.5.5
        "behat/mink-extension": "~1.2.0", // v1.2.0
        "phpunit/phpunit": "~5.7.0", // 5.7.27
        "guzzle/guzzle": "~3.7" // v3.9.3