Designing an API for service operations with closely related parameters

Question

I'm having trouble deciding how to design this service API.

public class GetCurrentValuesRequest
{
    public int ReferenceID { get; set; }
    public int[] FilterIDs { get; set; }
}

public class GetDefaultValuesRequest
{
    public int[] FilterIDs { get; set; }
}

public class GetValuesAsOfDateRequest
{
    public int ReferenceID { get; set; }
    public int[] FilterIDs { get; set; }
    public DateTime AsOf { get; set; }
}

public class GetValuesAsOfChangeSetRequest
{
    public int ReferenceID { get; set; }
    public int[] FilterIDs { get; set; }
    public long ChangeSetIDs { get; set; }
}

public class GetProposedValuesRequest
{
    public int ReferenceID { get; set; }
    public int[] FilterIDs { get; set; }
    public long ApprovalKey { get; set; }
}

public class GetValuesIfModifiedRequest
{
    public int ReferenceID { get; set; }
    public int[] FilterIDs { get; set; }
    public DateTime Since { get; set; }
}

public class GetValuesResponse
{
    public string[] Results { get; set; }
}

public class GetValuesIfModifiedResponse
{
    public string[] Results { get; set; }
    public bool IsModified { get; set; }
}

public interface IService
{
    GetValuesResponse GetValues(GetCurrentValuesRequest request);

    GetValuesResponse GetValues(GetDefaultValuesRequest request);

    GetValuesResponse GetValues(GetValuesAsOfDateRequest request);

    GetValuesResponse GetValues(GetValuesAsOfChangeSetRequest request);

    GetValuesResponse GetValues(GetProposedValuesRequest request);

    GetValuesIfModifiedResponse GetValuesIfModified(GetValuesIfModifiedRequest request);
}

I've thought about changing it to have make the IfModified request / response subclasses of the simple GetValues request response and only including one GetValues call. The server would return a different response depending on the input request, but that requires user to call IService this:

var response = (GetValuesIfModifiedResponse)serviceClient.GetValues(new GetValuesIfModifiedRequest() { ... });

I've also thought about placing IsModified in the simple GetValuesResponse, and only populating it if a GetValuesIfModifiedRequest is passed into it. But that seems a bit strange to include it in a result from a method which does not actually do anything with it. Also, it might throw of a user if they see it and expect to be able to use it in their code. bool? IsModified is better, but I'm not entirely sold on it just yet.

Any suggestions for how to best design this API?

Answer 1

In my opinion, your sole request object should look something like this:

public class GetValuesRequest
{
    public int[] FilterIDs { get; set; }
    public DateTime SearchDate { get; set; }
    public SearchType SearchType { get; set; }
}

public enum SearchType
{
    AsOf,
    Since
}

You can tweak this to your taste, but the point is that there is only one search date submitted, and the enum provides a switch mechanism between past and future.

You can then return an object thusly:

public class GetValuesResponse
{
    public string[] Results { get; set; }
    public CacheState CacheResult { get; set; }
}

public enum CacheState
{
    Modified,
    Unmodified,
    NotChecked
}

Answer 2

This looks like you're trying to create a dynamic query over http. Have you looked at OData? Since you're using WCF, there is built-in support as of 4.0 I believe for implementing OData called WCF Data Services, all you have to do is return IQueryable from your service methods. For convenience, you can create helper queries on your client library that wraps around the OData queries. So your service interface would now look like

public interface IService
{
    IQueryable<Values> GetValues();
}

And your client library would contain helper functions that call the service.

public class ServiceClient
{
   //Injected or initialized see docs under previous link on accessing a service
   private IService _service
   public IEnumerable<Values>GetFilteredValues(int[] filterIds)
   {
      //get the values matching passed in Ids.
      return from _service.GetValues().Where(v => filterIds.Contains(v.Id));
   }

   public IEnumerable<Values>GetFilteredValuesAsOf(int[] filterIds, DateTime asOf)
   {
      //get the values matching passed in Ids and created since the asOf date
      return from _service.GetValues().
             Where(v => filterIds.Contains(v.Id) && v.CreatedOn > asOf);
   }

}

The beauty of this is that the query happens server side. If it is backed by a Database, the database handles it.