I am starting developing in a new architectural paradigm over some legacy code we had. Let's call them v1 and v2.
On v1 we had models for different domains (e.g games) that nested all the information of the entity and also of the attributes. So you could get a response that nested everything related to the domain when you hit a endpoint. E.g/ v1/games would bring you the game + the players + the teams + the arena.
On v2 we're trying to be more resource oriented so you actually get the resource you're querying for (e.g) - You have a endpoint for games, and then you'll have an endpoint /games/{id}/players - where with the first you get the game and in the second you get the players and it's self documentary by the path what you're going to get.
On v1 we had this models where everything was included and either required or not. So our actual model would include references to the other "attributes"/objects - E.g/ Games model will have a players array. Whenever you were getting or posting you would actually user the same model, you would just get more information on the get that what you sent on the post.
class Game {
public $id;
public $datePlayed;
public $players = [];
public $homeTeam = [];
public $awayTeam = [];
}
On v2 models, we have been an actual representation of the database table (like the active record approach of modeling). So the game model would not include players (since that is a different resource).
class Game {
public $id;
public $datePlayed;
public $homeTeamId;
public $awayTeamId;
}
So far I think the end result is very good because we're actually getting the resource we need and not a nested version with a lot of verbosity and unnecessary data.
However I have a new challenge now. There are endpoints that need to return responses with nested resources which will not be the actual database representation. Since we're not on a perfect world and I don't want developers that use our API to actually make tons of request for all the attributes I need to come up with a solution that helps me deliver them some basic information of the related resources.
So for example returning to our Game endpoint -> for post I do want them to send me a payload that is the exact database object
{
"datePlayed": "2016-04-29T17:20:08+00:00",
"homeTeamId": 5,
"awayTeamId": 15
}
But for the GET I would like to decorate the response with basic data (not the whole object but just enough so that the developer get the basic information so that they only make a new request to get the complete related resource but not the basic information).
{
"datePlayed": "2016-04-29T17:20:08+00:00",
"homeTeam": {
"id": 5,
"name": "Killer clan"
},
"awayTeam": {
"id": 15,
"name": "Retry team"
}
}
At first I delegated this responsibility to the controller->repository who would create a new object upon request and return it on the GET method but would validate POST and PUT to the actual model. However this doesn't seem too maintainable on the long run since you have to dig into the code to understand what you're sending.
So I gave it a long thought and I have an idea to create a new set of models with the convention Stub (the part of a check, receipt, ticket, or other document torn off and kept as a record) that will declare the structure of the response. Eg:/ I would create a GameStub model class like this
class GameStub {
public $id;
public $datePlayed;
public $homeTeam = [];
public $awayTeam = [];
}
What do you guys think of this solution? Does it make sense?
Aucun commentaire:
Enregistrer un commentaire