Programming for APIs
There seems to be as much or more attention paid to “Apps” these days as there is to websites. Whether it be for iOS, Android, Blackberry, Adobe AIR, Silverlight or even the (gasp) Desktop, we as “web” programmers are often called upon to implement APIs for these things.
Sometimes it’s in addition to a website, and sometimes it’s a stand alone API that is only meant to service a specific need for a specific app. In either case, it’s a good bet that can easily get cornered by the temptation to do what you’ve done before. Usually, for Asp.Net folks, it means a simple asmx or (better still) a WCF service that can be controlled through configuration. Either of these choices is fine, but if you are just envisioning the scope of what you are doing, you need to step back from the actual implementation details and ensure that the functionality you wish provide from this API is not reliant on the service technology itself.
Just start from a basic data API, but keep in mind that everything you are working with may need to be stateless. That means no session state, no reliance on cached values (since your code could be deployed to a web farm) and no (or few) global variables. Once you’ve cut all the crap and spaghetti code from what will become your data access layer, you can be left with a set of simple methods that take some parameters and return an object or collection of objects.
Sounds easy to test, doesn’t it? That’s the point! You should be able to test the whole API before you even decide on whether the service is SOAP, JSON, ATOM or whatever. I recommend you do that. One thing to note, is that I would be wary, at this point, of copying and pasting code from “getting started” tutorials. By all means, read those tutorials and understand what they are doing, but don’t feel that you have to jump into one technology or some pattern that doesn’t resonate with you after playing around with it. Sometimes a standard data layer with static methods and custom objects calling custom written stored procedures in a database or writing files or whatever, is better than relying on some generic layer of logic like LINQ-SQL, Entity framework or nHibernate. Not that I’m saying you shouldn’t use these technologies, they can make your life MUCH easier and speed your implementation process up greatly. But it can also introduce unnecessary complexity into what should be a simple process of moving data from one tier or layer into another. Always remember that simple is better, and anything you don’t understand isn’t simple because you won’t be figure out what’s wrong if it breaks.
When you come to your objects that will store the data, be wary of using object that are creating by another framework like LINQ-SQL or Entity framework. These objects are sweet as a starting point because you don’t have to worry about all that typing, but you may run into situations where the serialization required by your specific object on a specific service protocol will need customization that you can’t do in a partial class. I won’t go into specifics here, but if you don run into the situation where you need to create your own custom objects, don’t hesitate. Just do what you need to do to ensure you understand how your objects are being created, serialized and de-serialized. It will be simpler and more reliable in the long run.
Now you’ve got a data access and/or a business logic layer that you can test, and you should go ahead and do that before you start implementing the service itself. You probably won’t, but knowing that you should have will help out later.
At this point, if you can, use Asp.Net 4.0. If you can’t ask yourself why not. Ask everyone why not. Do some research on WCF in .Net 4.0 (the biggest kicker is that in .Net 4.0 you don’t need to worry about multiple host headers screwing with your service). If folks won’t listen to you, start arguing and argue with all your might that you need to code this API in Asp.Net 4.0. Trust me, it will be worth the time you spend convincing yourself and them.
Now, make a decision and either code the thing for OData or simply implement it in WCF. Those are the only real choices that make sense, as far as I am concerned. WCF lets you do REST style APIs or SOAP style without re-coding everything, but OData is better. Why OData? Do some research on that too, and you’ll find out that in the real world, your API will be most useful in one of two formats: XML and JSON. OData does XML in Atom format, so it’s inherently readable in most browsers. OData lets you flip to JSON or JSONp without messing with your API. WCF is OK, but OData, if you can get your head around it, tends to be much better.
Oh, and OData in .Net 4 is implemented as WCF Data Services. It used to be called ADO.Net data services.
There are also a ton of client SDKs for OData, but XML is so easy to consume, your API consumers will be able to see the value of your API with just a browser.
That’s the real point – with a well written, simple and testable data layer, and OData on top of that, your API services will be reliable and elegant to use. Folks will WANT to use APIs that are easy to understand and reliable.
more later – joel.