Share via

Creating a new API (Part 2 of 2)

  • Article

POSTED BY: RENAUD LECOEUCHE, MSS Software Dev Engineer

In this post, I’d like to go through two other sources of information and constraints when designing a new API:

· Existing API (internal and external)

· Usability

In Creating a new API (Part 1 of 2) posted on May 30th, I discussed making the API do what is needed. This post is about making it easy for you to use the API.

Existing API
The first way to make it easier to use an API is to make it more familiar. Most of you are already familiar with other .NET technologies such as ASP.NET. Therefore, before we add a feature in the API, we always look at these technologies and consider whether we can re-use them. The most obvious example is Windows Workflow Foundation (WWF). Rather than inventing our own dialog designer we decided to leverage the WWF team’s work. This enables you to learn how to design dialogs more quickly and makes sure that your investment in learning this technology can be used across several Microsoft products.

There are many smaller examples. In a previous post, Alan and Gunnar mentioned the AsyncCompletedEventArgs base class and the need to call RaiseExceptionIfNecessary if you derive a class from it. The purpose of this is to get a consistent behavior with other APIs in the .NET framework. All EventArgs that provide asynchronous results do so. If you are interested in the topic, I recommend reading Framework Design Guidelines by Krzysztof Cwalina and Brad Abrams. The book provides guidance on creating new classes in a manner consistent with existing .NET classes.

Usability
API usability is a vast topic. Here are some examples of what we consider:

· How much code are authors required to write? Common scenarios should require few lines of code. When we started designing the dialog API we actually wrote several applications in SALT and in managed code to make sure that the dialog API compared favorably with RunSpeech.

· How discoverable is the API? Can authors find all the features? We think about this topic a lot, especially since we have two ways of writing dialogs: via the designer and in code. Some features are still somewhat difficult to find. For example, each workflow has a History property that lets you know what happened last in the workflow execution, but many people don’t discover it without help. Your feedback can help us identify these features and make them more prominent.

· Does the API force authors to make choices that are difficult to change? For example, how difficult is it to change Statement into QuestionAnswer? This is helped by consistency in the API. For example changing a statement to a question answer requires changing the type and adding a grammar. The other properties have the same names and do not need to be updated.

I hope these posts gave you some idea of the work we do behind the scenes to deliver an API. As always, feel free to comment on the blog or via the Connect website.

Comments