API Documentation
The Bing Webmaster API document starts here, but it gets a little confusing. For example, as you navigate around, you will see three similar, but different, navigation nodes (image @ right). As you navigate around, they seem to appear and disappear, which can be a bit confusing.
The actual methods are listed under the API Reference node, on the IWebmasterApi Members page. The API supports a SOAP interface, which if you are developing in Windows/Visual Studio with C#, simply follow the instructions on the Getting Started page and you’ll have basic connectivity pretty quick. I prefer JSON over XML/SOAP because it has smaller downloads and that means a more responsive application, and while that is also available, the documentation is a little skimpy about how to use it.
Finding Help
I am not a big one to ask for help, preferring to look up an answer. With the Bing Webmaster API, that process was short…and not sweet. There is a complete absence of helpful articles or postings on the subject.
The closest I could find to a support forum was the Bing Webmaster Forum (now closed), but even that contained nothing significant. The FAQ was written in 2010 and the API came out in 2012, so that’s of no help. There are a few more recent responses, but nothing about the API.
Functional Mapping
When I start working with a new API, the first thing I do is to map out the various method calls against the major groupings in the web user interface. This serves several purposes: first, because people usually look to the API to automate things they have done manually, and the web interface is what they are familiar with. A lot of APIs use a completely different naming convention for the API and their web interface. In my applications, I group these functions into wizards and try to name them consistent with the web terminology so people can find what they are looking for (intuitive = like something you are familiar with).
The second reason is that I need to plan my application interface, and understanding the various parameters for each function lets me reuse various design elements in the wizard panels. This usually means figuring out the parameter names and their data type (string, numeric, date, boolean, picklist, etc). It also helps to know which parameters are optional, and what default value is used if they are unspecified.
The third reason is that it provides a cross reference for validating queries — are the results the same? I find it surprising how some applications deliver slightly different results from the API, or require some special combination of parameters, to reproduce what people see in the web interface. If the numbers don’t match, we immediately lose all trust in the data. It could be the use of GMT/UTC date-time values instead of local times, or delivering percentages as whole numbers (1% = 1) instead of as fractions of 1 (1% = 0.01), or the use of codes in place of full country or language names.
Page Traffic or Inbound Links?
Here is the mapping that I built for the Bing Webmaster API. All parameters seem to be required, although some could have empty values (country, language). Some initial observations:
- they use the parameter ‘page’ in several methods as a page counter (integer), but in one method to specify a web page (string).
- some of the methods have examples with responses, which really helps in understanding some of the terse descriptions.
- it is not immediately clear what the differences might be between the parameters ‘url’, ‘feedUrl’, ‘page’ and ‘link’ might be. They all seem to refer to web links and mean different things in different methods…and not consistently.
- looking at which methods do not have a siteUrl parameter makes it really easy to identify the methods that are non-site specific.
- In my use case (reporting), I have little need for administrative operations, so I group them into Other.
