A Case Study in SDK Design

I’ve recently updated my Gofor WinPhone7 application to use a newer version of the YellowAPI WP7 SDK, and to my surprise there were a number of drastic changes in the new version. It took a bit of time to convert to the newer SDK, and I took a few notes of things I thought were a bit off while I was doing it. Here’s a summary that can be used as a case study in SDK design.

I want to start off this post by saying the Yellow API guys are awesome. They have a simple and easy to use web service for location-based searches, a great developer program, and are generous sponsors of all our HackDays and HackREGINA events. The dev team responds quickly to requests via their @YellowAPI twitter account, and they’re more than willing to work with any developers to help them release applications. When I tweeted that I had a few concerns with the new SDK design, they responded quite quickly that they’d be willing to listen to feedback and work on it. So here’s my feedback :)

Documentation

First off, and this was the biggest thing with me, was the lack of documentation both in the source code and on the website. The website doesn’t mention anything more than “Refactored code, now easier to use”, and doesn’t link to any sort of migration document. When you’re updating your SDK, one of the first things you should do is provide a “here’s the changes you need to make if you’re migrating from an earlier version”. This helps all your existing developer base make the move, without having to take random shots in the dark at what needs to change.

Something else that would’ve made it eaiser would be code-level comments. You know, the nifty intellisense notes you get when you’re filling in the parameters for a method or class? Those are the easiest and most accessable form of documentation you could have in an SDK as they’re always right there, telling the developer exactly what you expect for input. One example was the change to their FindBusinesses method. They went from a method that took a bunch of specific arguments, to something that just takes “what” and “where”. The what I can understand, but the where was just a string argument. To search at a specific city, you’d give the city name, but how do you pass coordinates? You actually need to look at their web serivces’ documentation and find out that coordinates need to be passed in a “cZ{long},{lat}” format. And I wasn’t even sure if that was the right way to do it until I tried it out. Having some level of inline comments, even if it was to just refer to the web service documentation, would’ve helped greatly.

3rd Party Requirements

The other major thing that kind of bothers me was the return type. Their SDK was refactored internally to use RestSharp for making web service calls. Which is a great library, and I highly recommend anyone who wants a better way to interact with restful web services to use. But, the YellowAPI SDK actually returns the RestResponse object from the RestSharp library. Now I have to learn what the heck a RestResponse object is and how I get data from it. This is a change from the previous SDK, where they returned typed objects representing the data and any error(s) that may have occured. I think returning a specific YellowAPI object rather than another 3rd party library’s object would be the preferred way of handling return values.

Non-intuitive Names

Another change that was a bit of a switch was the way a YellowAPI service object is created. Before, they were using a static class on which you’d set your app key, password, and other properties and then call methods against directly. Now they have an abstract class and concrete implementation with a constructor that takes those credential arguments. I do agree with the switch away from a static class, as that helps with being able to mock out and test your code (although an interface instead of an abstract class might’ve been better). I would’ve liked some documentation on the change in how you provide your credentials however. Also, the concrete class is called YellowAPIImpl, which is a pretty awkward class name, and I probably would’ve had to go searching for it if it wasn’t for resharper. Overall not big changes for an intermediate developer, but for any beginners it might be too confusing and create a road block preventing new people from using the SDK.

All in all the SDK still works, and it comes with a sample project when you download it to give you a good idea of how it can be used in an application, but there are definitely a few things that could be improved upon. Most of these relate to having documentation available, and lowering the required understanding to use the SDK. I shouldn’t have to go exploring if I just want to fool around with an SDK, it should be as accessable as possible.

Comments