MapForums

When the Virtual Earth Platform Team first began designing the Virtual Earth Web Services, we made developer ease of use one of our key goals.  After some researching and brainstorming, we eventually came up with a set of core API design principles for all Virtual Earth Web Services that helped guide us.

•         Keep only the most important properties as accessible as possible.

As much as we dislike creating and nesting several layers of specification objects, we also dislike wading through a slew of top-level properties just to determine what we actually need to pass in.

Given our distaste for either extreme, we chose a more centrist path for the Virtual Earth Web Services:

• All required data is located in the top-level properties of a request object.


• All optional data and execution settings are located under the separate options properties of a request object.

•         Minimize the input needed to execute the request successfully.

No one likes an API that requires entering every single piece of information every time you make a request.  The Virtual Earth Web Services saves you the effort by setting default values for optional data or execution settings -  even if you only specify a subset of the optional values.

•         Standardize input types, output types and method signatures.

Early on in the design process, we recognized that maintaining a certain level of consistency across all Virtual Earth Web Services would reducing the amount of surprise developers encountered moving from service to service.  With that in mind, we did the following when designing all of the Virtual Earth Web Services:

• Each Virtual Earth Web Service is built off of a set of common data types. This includes a common base type for all request objects (RequestBase), a common base type for all response objects (ResponseBase) and a set of shared core data types like shapes & units.


• Each service method follows the same input / ouput pattern - a RequestBase subtype goes in, a ResponseBase subtype comes out.

Eugene Shinn

Senior Software Development Engineer, Virtual Earth Platform