I'll explain a bit about how lazy-loading could be implemented.
Currently, when you instantiate an object from the API you can initialize it with just the id of the object. In other words, I can initiate an object for person Grant Morrison like so:
Now, there are more constructors than this, which are useful for a variety of things, but at the bare minimum you must initialize with the id of the object, and all constructors require the id. By using this most minimal constructor the only property out of the 20 or so properties that the person object has that is not null is id. So if I were to try to display this person's name, I'd try something like this:
But name is null. So we don't get good results.
With lazy-loading implemented (as opposed to the purely manual loading that's required right now), I don't have to manually call get the name property before I can try to retrieve it. The act of trying to retrieve it will automatically go out and get the data before returning the value. No more null returns.
The way the classes work is that there is a GetDetails(string fields) method that, when called, generates the API query to get the details data for the id of the instance of the object that you're calling GetDetails on, and it passes along the fields list that you give it (there is an overload with no parameters that, when used, gets all possible fields for that resource type). It then parses the data and fills in the properties you requested.
Example: If I wanted to get all the fields of data for grant_morrison, I would just use the following code:
Super simple. This is a one-stop function that generates the API query, retrieves the data, parses it, and fills in all of the properties for the Person object I created with id 40434. Here's the API query that it generates:
my_api_key is your ComicVine API key. At the very start of your program, you must called the APICommandBuilder.Initialize(string my_api_key) method in order to have your API key inserted into the API queries, and if you neglect to do so, the API will just return 0 results for everything.
Well, you can also just call GetDetails with the field list if you don't want to get ALL data for your object. So if I just wanted to know the name of the person with id = 40434, then I would have instead called:
This creates the following API query:
And just to further show the capabilities of my library, you could ask for as many fields as you want by just asking for them with + signs separating them. All of the resource classes have a Fields struct that allows you to easily pick from the available fields for that resource type. So if I wanted this person's name, birthday, and nationality, I'd just ask for it with the following code:
This creates the following API query:
Anyway, I feel that I've digressed a bit from the main topic here. Without lazy loading, you mustn't necessarily call GetDetails on the object with the field you want as part of the field list first. In essence, when you try to get the value of the property, it will check to see if it's null and if it is, then it will manually call GetDetails() on that field and then retrieve the result for you.
The one reservation I have about implementing lazy-loading is that it might encourage lazy-coding. If you're not thinking about all of the fields you will need for the various parts of your application at any given stage in its running, then you're probably coding very inefficient code. Because let's say that this one part of my application will use the 3 fields, name + country + birth, well you would want to manually call for them in a single GetDetails call with those 3 fields specified. But because you know lazy-loading takes care of retrieving that data for you, well, let it and don't manually retrieve the data, but just request the values of those 3 properties of your object. By this method, you're having the class do 3 queries against the API when you could have done this with just 1 query against the API had you utilized GetDetails before trying to access those properties.
So what do you think?