Investigate new request building model

[seanconnollydev]

It is prohibitively difficult to support new API calls. While the classes are relatively easy and safe to work with once established, every new case requires new classes or new combinations of classes (e.g. TeamPlayerCollection, LeagueTeamPlayerCollection, Leagues, GameLeauges, etc.).

I would like to explore new patterns for simplifying the addition of new API calls. Yahoo has defined structures (resources, collections, sub-resources) that can be enforced in code.

The first thing I would like to try is the use of dynamic typing paired with a clean service request builder syntax (e.g. Resource.WithKey("nfl")).

[seanconnollydev]

In the spirit of getting better at thinking through requirements, here are some thoughts to help me steer towards the optimal solution.

• Once the basic structures and resource definitions are in place, new combinations of resources and sub-resources should require no modifications to the client library.
• Simple requests should be expressible on a single line of code (e.g. _service.Get("nfl");)
• I should be able to specify as many sub resources for a requested resource as fits within Yahoo's structural rules for resources. (e.g. Request specific teams and draft results from a league in the same call)
• Support nested sub-resources (e.g. Request specific teams with their stats and draft results in the same call)
• Request calls should be easily unit testable
• Return types should be type safe (e.g. not dynamic)
• The API should minimize the number of web requests made to the Yahoo API by allowing client callers to tailor custom requests.
• It should be very difficult (or impossible) to compile a request that does not conform to the Yahoo API's resource structure.

[seanconnollydev]

Some terminology that might be useful:

• WithKey (when a game_key, team_key, etc. needs to be specified)
• Include (indicates a sub-resource), also considered AndIts or With

Some examples:

_service.Get<Game>("nfl").AndIts<Leagues>("key1", "key2");
_service.Get<Game>("nfl").Includes<Leagues>("key1", "key2");
_service.Get<Game>("nfl").With<Leagues>("key1", "key2");

LeagueRequest leagueRequest = _service.Get<League>("league_key");
TeamRequest teamRequest = leagueRequest.Include<Teams>("key1", "key2")
teamRequest.Include<TeamStats>();
teamRequest.Include<TeamDraftResults>();

Given the above block, I like "Include" better. It works OK with the single line case:

_service.Get<Game>("nfl").Include<Leagues>();

[seanconnollydev]

Another option is to use terminology like AsSubResorceOf. For example:

_service.Get().AsSubResourceOf("nfl");

However, I think this will not as easily support the case with multiple sub-resources.

[seanconnollydev]

I think the above pattern will work for creating clean requests, but it doesn't really solve type safety.

One thing I can consider is type safety with simple, single resource calls and dynamic objects with anything that requires a sub-resource.

I can also consider a pattern where the parent resource's type is passed as an argument to a sub-resource.

[seanconnollydev]

Linq kind of solves this problem I think so it might be worth taking a peek at.

[seanconnollydev]

DynamicObject and ExpandoObject both only have run-time checking. I think the problem I am trying solve is somewhat different. Given a method call or series of method calls, the type of result should be predictable so I think there is still an opportunity for compile-time checking. I could create a new type for each combination of call, but I am trying to avoid a proliferation of types and adding unnecessary work.