RESTful API - How do I return different results for the same resource?

Question

Question

How do I return different results for the same resource?

Details

I have been searching for some time now about the proper way to build a RESTful API. Tons of great information out there. Now I am actually trying to apply this to my website and have run into a few snags. I found a few suggestions that said to base the resources on your database as a starting point, considering your database should be structured decently. Here is my scenario:

My Site:

Here is a little information about my website and the purpose of the API

We are creating a site that allows people to play games. The API is supposed to allow other developers to build their own games and use our backend to collect user information and store it.

Scenario 1:

We have a players database that stores all player data. A developer needs to select this data based on either a user_id (person who owns the player data) or a game_id (the game that collected the data).

Resource

http://site.com/api/players

Issue:

If the developer calls my resource using GET they will receive a list of players. Since there are multiple developers using this system they must specify some ID by which to select all the players. This is where I find a problem. I want the developer to be able to specify two kinds of ID's. They can select all players by user_id or by game_id.

1. How do you handle this?
2. Do I need two separate resources?

Answer 1

Lets say you have a controller name 'Players', then you'll have 2 methods:

function user_get(){
   //get id from request and do something
}

function game_get(){
//get id from request and do something
}

now the url will look like: http://site.com/api/players/user/333, http://site.com/api/players/game/333

1. player is the controller.
2. user/game are the action

If you use phil sturgeon's framework, you'll do that but the url will look like: http://site.com/api/players/user/id/333, http://site.com/api/players/game/id/333

and then you get the id using : $this->get('id');

Answer 2

You can limit the results by specifying querystring parameters, i.e:

http://site.com/api/players?id=123

http://site.com/api/players?name=Paolo

Answer 3

use phil's REST Server library: https://github.com/philsturgeon/codeigniter-restserver

I use this library in a product environment using oauth, and api key generation. You would create a api controller, and define methods for each of the requests you want. In my case i created an entirely seperate codeigniter instance and just wrote my models as i needed them.

You can also use this REST library to insert data, its all in his documentation..

Here is a video Phil threw together on the basics back in 2011.. http://philsturgeon.co.uk/blog/2011/03/video-set-up-a-rest-api-with-codeigniter

It should go noted, that RESTful URLs mean using plural/singular wording e.g; player = singular, players = all or more than one, games|game etc..

---

this will allow you to do things like this in your controller

//users method_get is the http req type.. you could use post, or put as well.
public function players_get(){
  //query db for players, pass back data
}

Your API Request URL would be something like:

http://api.example.com/players/format/[csv|json|xml|html|php]

this would return a json object of all the users based on your query in your model.

OR

public function player_get($id = false, $game = false){
  //if $game_id isset, search by game_id
  //query db for a specific player, pass back data
}

Your API Request URL would be something like:

http://api.example.com/player/game/1/format/[csv|json|xml|html|php]

OR

public function playerGames_get($id){
  //query db for a specific players games based on $userid
}

Your API Request URL would be something like:

http://api.example.com/playerGames/1/format/[csv|json|xml|html|php]