Representations¶

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.