The problem with a lot of REST framework implementations, like Rails, is that it acts as nothing more than a database record serializer/deserializer. A vanilla Rails resource looks something like this:

  <post>
    <id>1</id>
    <title>This is a post</title>
    <comments></comments>
    <author_id>100</author_id>
  </post>
  

When you consume this resource, you end up having to munging database foreign key IDs into an URL string. For example, if I want more data about the author of the post above, I'd have to grab <author_id/> and plug into another endpoint, like /authors/:author_id. Who knows if /authors is the correct endpoint? Even if it was, if that endpoint changes, it could break the URLs that I munged together.

These "RESTful" implementations should really look like is the following:

  <post href="/posts/1">
    <id>1</id>
    <title>This is a post</title>
    <comments href="/posts/1/comments"/>
    <author href="/authors/100"/>
  </post>

Given such a format, I don't have to guess what the endpoints are for associated resources; I just look at the href and grab the resource if I want it.

A collection could include dataset navigation information, such as:

  <posts>
    <link rel="prev" href="/posts/?start_id=51&items=50"/>
    <link rel="next" href="/posts/?start_id=101&items=50"/>
    <post href="/posts/1">
      <id>1</id>
      <title>This is a post</title>
      <comments href="/posts/1/comments"/>
      <author href="/authors/100"/>
    </post>
    <!-- more posts here... -->
  </posts>
  

Now I can implement a less breakable client that doesn't need to munge URL endpoints with database foreign keys. Furthermore, I can navigate through datasets by following the <link rel/> tags.