"Execute" API in a Service Oriented world

"Execute" API in a Service Oriented world

If you look at Microsoft Dynamics CRM V3.0 web services APIs, you’ll notice a number of drastic improvements compared to the previous versions of CRM.  Besides the facts that you will see a much deeper integration with Visual Studio (IntelliSense = self documenting API = much faster/productive coding) and stronger compliance with web service standards (enables better interoperability and platform independent development through WSDL and WSI standards), the API design itself has improved significantly in its shape and use cases.  So I thought I spend a little bit of time writing about why we designed the APIs the way they are designed in V3.0.  

The new design is much more elegant, generic and consistent across all the Business Entities, including the custom ones that you can create yourself. The APIs have been designed around developer personas (check out this video on API usability and personas) in a Business Entity agnostic (you can have fun with derived classes and use the same interface for any type of Business Entity) and with a single web service endpoint.  Think of personas as different types of developers who build different types of applications for CRM.  We considered a range of developers from junior VB type developer for our more basic scenarios to an experienced C# developer for our more complex scenarios and set the goal to make both groups productive when using our APIs (not necessarily the same set of APIs). 

The design has the APIs bifurcated into two categories: 1) Simple APIs for simple and common use cases (e.g. getting data in and out of CRM).  These are super easy to use, need minimal coding and work for all the CRM business entities including custom ones. Of course!  2) More comprehensive APIs (through Execute – see below) for complex business operations in CRM. The tough challenge for this category was to decide how we expose our rich API functionality through a single web service, in a way that is easy and discoverable for developers to learn and be productive in developing code against them.  The second category is the one I want to focus on here. It is designed around Service Oriented Architecture (SOA) principals.  These principals are useful when building distributed applications that communicate through messages based on a contract.  In order to use these APIs, there are four simple concepts to learn about:

1)     Message: message is a piece of information that is sent to or receives by a service in distributed applications.

2)     Request messages: these are messages that request an action from the target service that receives the message. In CRM terms, let’s say you want to merge two accounts or update a customer contact; each of these actions has a request message associated with them that can be sent to our web services for processing. 

3)     Response messages: these are messages that are returned from after the requests are processed by the CRM web services.  They include the result of the actions that you have requested.  Let’s say you request from the CRM web services to create a new customer account, the response message will include the id of the customer account that is created to confirm that your message was successfully completed

4)     Execute method [Response Execute (Request Request)]: this is a single web method that allows you to send Request messages and receive responses.  There are a couple of hundreds of CRM Requests available for developers to invoke various operations and actions in CRM all offered through our web services.  In other words, the entire CRM API functionality is defined as a collection of Request messages that can be passed into a single method.

Why Execute model is important? What are the benefits?

1.      If you are building distributed applications in a SOA world and with live services, you feel at ease with the Execute API since it is desinged based on messages and contracts principal enabing high interoperablilty and less painful application integration.  

2.      Execute signature itself has a high longivity. One of biggest development pains, both for us as a platform and for our devloper partners is to support multiple versions of an API in the field and manage versioning, fnctionality and interface differences.  Since Execute signature takes the base Request class the prcess of adding new business value to our plaform is simply acoomplished by adding new Request messages without the need to change any interfaces.  This gives us a lot of flexibility to manage new features and different versions of CRM compared to the conventional approach of “create a new interface for new functionality”.  Of course, in order to keep backward compatibility, we will keep all the older messages functional and use a simple policy to describe what messages are supported for what version of Execute (versioning is a bigger discussion, perhaps in upcomming blogsJ). 

3.      Since the entire Request messages are defined in CRM metadata, the management of APIs are automated and carried out at metadata level with almost no coding! This translates into an agile platform and consistent API set that is able to continiously add value to our developers as well as enabling them to build more reliable and generic applicatiosns.  

4.      Request messages can be extended to support more complex operations.  Ultimatly Requests become a set of instructions for CRM platform to do things for you (e.g rut this workflow definition) enabling a highly extensiable service in the cloud that is capable to execute  cusotm messages.  The sky is the limit for the future of this API,  imagine scenarios where we allow ISVs to add their own custom Requests to CRM platform and extend us in new ways. 

5.      Thanks to intitive naming convention used for Request messages, and integration with Visual Studion, you can easily find them through IntelliSense right inside your development environment.   As an added bonus you can also  discover what Business Entities are supported by each Request messages while typeing code and without resorting to documentation (power or self documenting code!).  The Request messages start with an action name (e.g. MergeAccount, SendMail) and are always appended with the word Request.  Each Request has a corresponding Response class.  Here is an example in Visual Studio where I started to type Send and got a list of requests in IntelliSense to choose from:

 

All in all, as you can see the Execute API has a lot of benefits and the future is bright for this design so download the SDK and have some fun writing some cool applications for CRM.