Ease of development

Moving to ASP.Net Web API over all has been a very pleasant experience, working in the framework for us has been pretty painless.

That said, moving from release to release has been quite a chore:

• The move from WCF to ASP.Net MVC was quite jarring.
• The move through various beta builds was also painful, the removal of OData caused us quite a lot of rework (but ultimately for the best I think).
• The move to RTM though, almost completely without issue (even though the list of changes was quite long - they were largely additive, not really breaking anything we already had in place).

Ease of integration

We found it pretty easy to integrate the Web API parts into our plugin infrastructure - one area we did struggle with a little was getting the Monorail routing engine to dispatch the API requests correctly - I didn't bother covering that in this series as it's a fairly niche issue.

Also keep in mind that as I write this, the RTM of ASP.Net Web API has been available for less then a week though - so we were certainly early adopters - I think now that the API is stable for the RTM, and as progress continues on out-of-band support for OData, people starting new API projects will have a much easier time of it then some of the people adopting this technology earlier on in the release cycle.

Total development effort for the API has been in the order of 2 developer months, which resulted in 92 controllers (at last count), automatically generated documention, good test coverage and some simple extension points for 3rd party developers to use when extending the API to include features for their own plugins - I'm pretty pleased with that overall!

What's Next

Nothing is ever done, and we have plenty of ideas for features we want to add to the API in the future:

PATCH support

PATCH support - I have been looking with interest at the latest OData WebAPI support previews approach to PATCH via a lightweight dynamic object representing the Delta, we are also very interested in Matt Warren's Eval based patching feature in RavenDB, which combined with our TQL and OData based filtering could provide a very powerful (though certainly not particularly RESTful) approach to updating application in Enterprise Tester in bulk.

Activity Stream API

Activity Streams - we have an activity stream implementation, which does support plugins posting events for a user or set of users activity streams within the application - next steps would be to expose this via an API (likely via the the http://activitystrea.ms specification).

Webhooks

Webhooks - Webhooks would support a number of useful scenarios for people integrating with the API - And also thinking about ways we could make it possible for people to compose multiple applications together via webhooks (there is a brief discussion on this topic here, with some good comments).

Custom Media Types

Embracing custom media types - so far we have been using application/json, which in effect is enacting the anti-pattern of tunneling the real media type, relying on consumers of our API's to refer to human-readable document (albeit nice human readable documentation!) to determine the schema for those representations.

Shifting to custom media types would be a good move in this case - programmable web had a good post on this a while back - but is likely not something we would do until we feel the API is stable.

Granular OAuth security

Currently the OAuth implementation is at a user level - but why give a consumer of an API access to features/data they don't need.

Security is currently conext-specific so this will likely take the form of an API consumer requesting a set of required permissions, along with an associated scope (project-specific or application-wide) as part of fetching the request token - and these scope restrictions the being applied to any security checks.

Implementing this delegation is actually likely to be less challenging then the refactoring of our permission structure to be more granular to suit the requirements of an API, as opposed to the existing UI usecases.

Usage Metrics/Tracking

Anonmyous usage metrics for the API would be very valuable when it comes to making decisions about changing aspects of the API.

Additionally tracking usage (including the type of usage, IP address etc.) would be valuable especially for instances of Enterprise Tester externally accessible on the internet (Either hosted or self-hosting customers).

FYI - StrathWeb has a post on implementing this via 2 DelegatingHandler's which might be a starting point for anyone looking to implement this themselves.

Wrapping Up

So this is where I end my series on the API development for Enterprise Tester - hopefully this series has been interesting to at least a few of you embarking on implementing your own API's for existing applications.

Describing the Experience

I think if I had to describe API development for a large existing application, it would be Cathartic - It's an opportunity to revisit old code, review decisions you made in the past, and re-imagine what interacting with your application can be like - it's quite cleansing/refreshing, as it's not often you implement a feature that touches on so many parts of an application at one time, that isn't some death march of restructuring and refactoring to please the gods of static typing.

Resources

I found these blogs/websites particulary useful while working on the API:

• StrathWeb - Filip Woj's blog
• Glenn Block's blog
• Rick Strahl's blog
• Collection of popular WebAPI bloggers
• Alex Jame's blog, great for keeping tabs on what's happening with OData on WebAPI
• ASP.Net Web API Discussions on Codplex

Previous Parts

• Intro - Enterprise Tester API Series
• Part 1 - Links, absolute URL's and JSON rewriting.
• Part 2 - "Expand" implementation and view model mapping.
• Part 3 - Generating API documentation.
• Part 4 - OData, TQL and Filtering.
• Part 5 - Authentication - Session, Basic and OAuth.
• Part 6 - Long running tasks.
• Part 7 - WebAPI Testing.
• Part 8 - Anatomy of an API plugin.