Best approach to multiple data interfaces

Topics: Web Api
Nov 30, 2011 at 8:46 PM
Edited Nov 30, 2011 at 8:49 PM

Hi, I'm just getting started with Web APIs and am having a lot of fun. I am looking to make use of them in a new project, and I find myself asking some philosophical questions about the approaches they are opening up.

My basic problem is: How should I structure my services for interfacing with the same data in a variety of ways?

Using the ContactManager as an example:

  • Say I have a page that only needs a few fields (e.g. Name) organized in a specific format (JSON).
  • And I have a page that requires the full Contact object, including some dependant objects (e.g. Addresses, Phones, etc.) in XML.

Also, consider that both pages may require the ability to filter or query results.

You guys have talked before about using IQueryable interfaces to accomplish lazy loading - grabbing only what is needed from the database. I also like how robust use of media type formatters allows us to reserve segments of the URI for identifying conceptual resources, then using formatters to target them toward different flavors. But I am beginning to wonder where best to draw the line.

If I used formatters for everything, I might have:

  • /contact/simpleJson
  • /contact/simpleJson?$Top=1
  • /contact/fullXml
  • /contact/fullXml?$Top=3

However, I believe that when using a formatter, the value result has already been obtained from the service, right? So, if the full contact object required some database table joins, but the simple format did not, then this would not be lazy enough to save us any database IO time.

But, if I used separate services to provide more useful querys:

  • /contactSimple/json
  • /contactSimple/json?$Top=1
  • /contactFull/xml
  • /contactFull/xml?$Top=3

This way I don't have to worry about the query not being appropriate for the task, and I can more often use common or built-in media types. On the other hand, I will probably end up duplicating more aspects of the models and repositories / database code. And conceptually, this does not seem quite as RESTful to me...

I appreciate any examples and insights any of you can provide!

Dec 6, 2011 at 5:00 PM

Any thoughts? (I thought you guys would eat this up!)