Formalizing the public API as per SO API names

May 25, 2010 at 5:48 PM

(Moving the discussion here, as per Luke's request)

You do have amake good point - having a sync client for the .Net 4 developers does simplify things a bit. To address this, I would suggest we come up with two interfaces - IStackOverflowClient and IStackOverflowAsync.

However, I do not necessarily agree with the SL async client being named as the .Net sync client. As you can see from the library source code, that actually makes it hard to maintain the same code base for both .Net and SL. Imagine a client that wants to be able to build for both WPF and SL - any SO.NET API usage will have to be #ifdef-ed to account for the same client type name, but different method signatures. Whereas if the SL client is named StackOverflowClientAsync, the same client code would compile happily for both .Net and SL. And I don't see the presence of the Async suffix necessarily as an impediment - after all, it does make it clear that the SO.NET API model is async.

That discussion aside, I still think that taking now the breaking change to introduce the interface(s) and rename the methods would be a good thing. The SO API is maturing quickly and people want to build against it. Hopefully, they will pick SO.NET for their apps; but that means that introducing this breaking change later will become harder.

Thus, even i we don't agree on the sync/async discussion now, we can (and should) at least introduce IStackOverflowClient and IStackOverflowClientAsync and fix the method names and signatures.

---------------------------------------------------

Franci,

 

I like the idea of having the client implement an interface. It just makes things much easier to understand and helps with versioning. The reason that I haven’t implemented it because I don’t really agree that the Sync and the Async versions of the client should implement the interface. The whole reason the sync version exists is because I think most .Net programmers are comfortable with the synch calling conventions. You call a method, you get a response as the return type. If all of the methods return void, I think that will be very confusing to people using the library for the first time. There is not really much precedence for the pattern of void methods which take a delegate as the main way to consume and API in the .Net BCL (outside of Silverlight).

 

There is a delicate balance I want to maintain between making the library very approachable/easy to use and allowing advanced scenarios. I would consider the async pattern of a void method with a delegate as an advanced scenario. Anything that requires the use of lambdas or delegates (that is not a common event handler) is advanced in my opinion.

 

I also like the fact that the class is called StackOverflowClient in both the synchronous .Net world and the asynchronous Silverlight world. I think it is easier to transition your knowledge between the two platforms. Also, having the class be named StackOverflowClientAsync in the Silverlight world just doesn’t fit since everything has to be asynchronous.

 

To be clear – these are just my thoughts on the subject and I am not decided. I really appreciate you bringing up these issues so that they can be discussed and the library can be improved as a result. Please let me know what you think so we can continue the discussion. Perhaps it would be better to move the discussion from email to the online discussion forum (http://stackoverflow.codeplex.com/Thread/List.aspx).

 

Thanks,

Luke

 

From: Franci Penov [mailto:francip@yahoo.com] 
Sent: Monday, May 24, 2010 9:06 PM
To: Luke Foust
Subject: Breaking change proposal

 

Luke,

 

I just uploaded a patch with a proposed SO API interface, which StackOverflowClientAsync should implement. The patch currently contains only the interface, so that you can look at it without being distracted by the noise. However, adding this interface will require breaking changes to the naming of the methods.

 

The reason I think this naming is better is that it follows very closely the actual SO API urls. This makes the methods predictable and the ramp up time for developers that know SO API shorter, as it's really easy to pick exactly the method one needs.

 

I also have a second proposal - to get rid of the current sync client until the object model and the public API is settled upon, after which we can reintroduce it back. My main driver is that I'd actually like to have the sync and async clients implement the same interface and differ only by the internal implementation; i.e. the sync client also take an Action<Questions> onSuccess delegate, instead of returning the results.

 

Franci

.

 

Coordinator
May 25, 2010 at 7:57 PM

I agree that we need to get these breaking changes in soon. I also want to change the IUrlClient interface to return an HttpResponse instead of just a string. This will allow us to return other information with the response (such as header values) and also make the Synchronous client more like the asynchronous client. I will work on getting these changes in tonight or tomorrow.

In addition to these changes I am looking at ways to include the paging and rate limit information with each response. I will start another discussion thread with my proposal so I can get your feedback.

Thanks,

Luke