How can I publish resource statistics via the RESTful API?

Question

I create an API for my web application and get it until I reveal all the resources that my application uses, for example. /users , /roles , /posts , etc. no problem.

I am now fixated on how to expose statistics on some of these resources in a RESTful way. It does not look like the statistics resource, since GET /statistics/1 could be everything, and the results are likely to change every request, since the statistics are in real time, so it will not be cached.

Background:

For each of the /users on the system, the application periodically requests the Steam API for the /games they play and the /servers in which they play, and saves this information along with the timestamp in the /states resource.

This information is aggregated to show the number of the most popular games and servers in the standard HTML pages /statistics/games/current-usage and statistics/servers/current-usage . Illustrative screenshots: servers , games (taken at different times).

EDIT: Sample Data for Core Resources

 "state": { "id": 292002, "user_id": 135, "game_id": 24663, "server_id": 135, "created_at":"2014-06-22 21:12:03" }, "user": { "id": 112, "username": "ilumos", "steam_id_64": "76561197970613738" }, "server": { "id": 135, "application_id": 24663, "name": null, "address": "192.168.241.65", "port": "0" }, "game": { "id": 24663, "name": "DEFCON", "steam_app_id": 1520 } 

EDIT 2: Does REST allow endpoints to use a timestamp as a resource identifier? eg:

GET /statistics/1403681498/games to get an answer like this:

 [ "game": { "id": 123, "name": "DEFCON", "users": [ { "id": 7654, "username": "daryl", "server": { "id": 127, "ip": "123.123.123.123", "port": "27960" } }, { "id": 135, "username": "ilumos" }, ] } ] 

Answer 1

I am going to create a usage repository, since all these statistics will be used by other resources, either "right now" or at a historical point in time.

My URIs will look like this: GET / usage / {resource_name} / {resource-id}

 GET /usage/games/ collection of games in use right now (with user totals) GET /usage/servers/ collection of servers in use right now GET /usage/games/?timestamp=1234567890 collection of games in use at {timestamp} GET /usage/games/1 usage of game with id 1 right now GET /usage/games/1?timestamp=1234567890 usage of game with id 1 at {timestamp} GET /usage/games/?user_id=123 usage of game with id 1 filtered to show only user with id 123 

And in the future I can expand the resource, for example, to return the use for electricity use

 GET /usage/phases/ collection of phases in use right now (with power draw totals) GET /usage/phases/1 usage of phase with id 1 right now GET /usage/phases/?timestamp=1234567890 collection of phases in use at {timestsamp} (with power draw totals) 

If not, then something frantically non-RESTful about it seems to be the most appropriate way to expose this information.

Answer 2

You have many non-completely unfounded options.

You can

• Include statistics with each answer. Will all customers statistics? Lots of statistics? Maybe something like GET / games? OrderBy = numPlayers- & offset = 0 & limit = 10 will work if all you track is the number of players.
• has an endpoint /statistics/{statisticId} . This is not essential.
• has an endpoint /games/{gameId}/statistics .
• has an endpoint /statistics/games/{gameId} .

Indeed, we have nothing to tell you that the best way to implement this is because we do not have enough information.