How can I represent something like “latest news” in REST api?

Question

Can't figure out how.

1) Resource identification. How do I identify the resource? Something like this? /latest_news/<id> That doesn't seem right.

2) Now suppose you have a URL for the resource latest news. Now each request for the same URL may give you a different representation. Does it violet any constraint of REST?

3) What about the stateless constraint on REST server? The wiki says:

The client–server communication is constrained by no client context being stored on the server between requests.

In order to serve latest news, a server must do some tracking which is the internal state of the server. However, I believe the server can still be called stateless in the sense of REST stateless constraint because that state is not client context. Or did I miss something?

Thanks in advance.

Answer 1

Now each request for the same URL may give you a different representation. Does it violet any constraint of REST?

Not inherently. It depends on how the request are different.

• If they are different in time (as latest news suggests), then that's perfectly fine.
• If they are launched by different users who each get personalized content, that's fine too.
• If they are different based on implicitly knowing this user's past actions, that is not okay, as this means you're tracking/relying on a user state and thus are not working stateless.

In order to serve latest news, a server must do some tracking which is the internal state of the server.

The "state" in "stateless" is referring to a user state. I'm not quite sure what you mean by server state, but if you mean things like checking the database (or a third party) for the latest news, that's obviously allowable.

For example, let's say your user loads your page, which calls /latest_news/ (no parameters), and thus receives articles A,B,C. While he is reading those articles, D and E are added to the server.

A second user calls /latest_news/ (no parameters) and receives A,B,C,D,E.

At a later point in time, the first user calls /latest_news/ (no parameters) again, and you intend to only give him D,E because he has already seen A,B,C.

The last part in italics is the issue. You're relying on knowing which articles the user has already read, which means you're tracking their state.

How can I represent something like “latest news” in REST api?

Simply put, your return values cannot be decided based on things you've secretly tracked about the user (implicit parameters).

What would be acceptable, however, is using explicit parameters. For example, /latest_news/?since=C (which retrieves all articles uploaded after C) is perfectly acceptable, as the server is giving the client exactly what they explicitly ask for.

Answer 2

Good answers so far but let me add another perspective. What is “latest news” but a sort decision?

Isn’t “latest news” just “news” that’s been sorted in descending order by datetime?

Your question ascribes no special constraints to the set of “latest”, so to me the best design is to just apply that as the default sort of your list of news articles (which seems common anyway) like, /news. This is shorter, easier to type and in my opinion more expressive.

Answer 3

1 You could use an alias

GET /news/latest-news/

To identify a specific "latest new", your approach is right

GET /news/latest-news/{latest-news-id}

2 Not exactly. Representation and content are not the same. While the content might change from day to day, your representation should not change. For instance, the response to the #1 could be a list of news' representations, formatted as JSON, XML, HTML, plain text. This will not change from request to request. What might change is the content, the news being retrieved. The resources' state might change and hence the content of the response.

3 This is another subject. The key for you to keep the server stateless is assuring client provides everything server needs to respond to the request so that the server doesn't need to hold and track the client's previous requests (whether the client is logged or not, whether the client has visited the page X, whether the client did click here or there).

Think in your client as an isolated application. Such application holds its own state (current page, latest action, current new visited, etc) based on the user's activity. Such state should be kept by the client and never delegated to the server. Otherwise, the server is holding "the sate" of the client, turning the server into stateful, since it holds every clients' state. So, make sure everything server's needs to respond is provided by the client (ids, auth tokens, query params, body params, etc) in every single request, and the client has everything it needs to request resources to the server.

In order to serve the latest news, a server must do some tracks which are the internal state of the server.

Of course, resources on the server-side will be always in one or another state and it's server's business to be capable of tracking, holding and retrieving such state. The data indeed is stateful, what should remain stateless is the "dialogue" between client and server. The server should not hold information regarding the client to resolve further requests from the same client.