Understanding the abstract jargons in REST

Question

Not sure whether it is here to ask these basic questions about REST...

The more I try to understand REST and want to implement it, the more I get confused. I think probably because of those abstract words I see when people come to teach you what a REST is. For instance,

REST from wikipedia,

Representational state transfer (REST) is an abstraction of the architecture of the World Wide Web; more precisely, REST is an architectural style consisting of a coordinated set of architectural constraints applied to components, connectors, and data elements, within a distributed hypermedia system.

And from this link

1. Representations of resources should be uniform

2. Use hypermedia—not URL schemes or resource name mapping—to represent relationships

3. Use a single entry to an API, hyperlink from there (hyperlink? why not hypermedia??)

4. Include a “self” link in your representations

5. REST doesn’t just mean spitting out ActiveRecord models as JSON (so what should you spit out??)

So, what does it mean by these abstract jargons below?

1. Representations,
2. resources,
3. URL schemes,
4. hypermedia (what the difference of it from hypertext or hyperlink???),
5. resource name mapping—to,
6. ActiveRecord models

Can you explain them in a concrete examples?

Answer 1

Representation is the name given for the complete set of bytes that are sent over the wire when you make a request to a resource using a link.

Resource is a any concept that is important to your application and you wish to expose it to a client application. A resource is identified by a URL.

Technically an URL Scheme is the first few bytes of a URL that appear before the colon. e.g. http, urn, ftp, file, etc. However, I suspect in the context you are seeing it, it means a convention for organizing the paths segments and query string parameters of and URL and assigning a significance to those pieces of the URL.

From the perspective of REST, a server can create URL conventions, but clients should know nothing about those conventions.

Hypermedia is a classification of media types that support hyperlinks. Hypertext is an older term that is almost synonymous with hypermedia. In theory hypermedia does not need to be a text based format. So far I'm not aware of any hypermedia formats that are not hypertext.

Hyperlink, link and web link are synonymous.

Unfortunately these terms are abstract by definition. There are many different ways to implement these concepts.

ActiveRecord is an implementation concept that is often used to contain the data that will be used to build a representation of a resource. However, if you limit yourself to only being able to create resources from ActiveRecord instances, you will likely struggle to implement an effective REST API.

---

Representations of resources should be uniform - This makes no sense to me. There is a REST constraint called "Uniform Interface". However, this constraint refers to using a consistent interface to enable building layered applications. i.e. When a client wants to talk to server, you can slip a proxy, load balancer, cache in between and the client and server don't know the difference because the interface is consistent.

Use hypermedia - Hypermedia helps you to decouple your client and server to allow either to evolve independently. If this is not important to you (i.e. you can always deploy your client javascript at the same time as the website) then you are not going to get a whole lot of value out of it.

Use a single entry to an API - See previous point. If you need independent evolvability then explore some more.

Include a “self link in your representations And again...

REST doesn’t just mean spitting out ActiveRecord models as JSON REST is an architectural style of the boundary of your application. Exposing ActiveRecords as Resources ties your client to implementation details of your server. Also, HTTP is limited to just a few methods (GET, PUT, POST, DELETE, OPTIONS, HEAD). In order to compensate for this limited vocabulary you will need to create Resources that are nothing to do with records in a database.

Answer 2

Many are quick to point out that "REST," as typically used, isn't really REST, as originally defined.

There's endless (and pointless) discussion and debate around this topic, but from a practical standpoint I prefer to think about "resources," and how best to expose them.

The concept of REST may be instructional in this regard, even if common implementations diverge from the source.

In the end, we're programmers and have to build things that meet today's objectives, knowing they won't be tomorrow's.