Introduction

This is the documentation for the MSDN/TechNet Publishing System (MTPS) Content
Service. The MTPS Content Service is an XML web service that provides access to
the content stored in MTPS. This includes, for example, the content available at
http://msdn2.microsoft.com/library.
Using the MTPS Content Service, developers can integrate documentation, technical
articles, whitepapers, images and the other content available from the MTPS system
into their own applications.

The MTPS Content Service requires no registration nor authentication.

The MTPS Content Service is a read-only service; no facilities are provided for
updating or amending content.

A short (currently 8) sequence of alphanumeric characters that - along with a version and a locale - uniquely identifies
a content item. Note that for historical reasons, a short
ID is expressed in XML with the element name "contentId". Every content item has
exactly one short identifier. Example: ms224917.

A GUID that - along with a version and a locale
- uniquely identifies a content item. Every content item
has exactly one GUID. GUIDs in MTPS are expressed using .NET's "D" format. Example:
10447DD7-07A1-4856-B00E-6F31465AC63F.

A freeform string that - along with a version and a
locale
- uniquely identifies a content item.
Aliases serve as "friendly names" for content items. A content item may or may not
have an alias. Example: System.Xml.XmlWriter.

A URL that points to a content item. In some situations, this can be used in place
of one of the other content identifiers. Note that
it can contain version and locale information,
which may override or be overridden by the locale and version specified elsewhere
in the content key. Example:
http://msdn2.microsoft.com/eak978d4(en-us,VS.80).aspx.

Identifies a particular variant of a content item. For
example, distinct content items describing the .NET 1.1 and .NET 2.0 flavors of
the System.Xml.XmlWriter class may exist in the MTPS database. A version string
identifies unambiguously which variant is desired. Versions are formatted as a dotted
pair combining a product family and a product version. Version is not used to
retain edit history of a content item - merely to allow documentation for different
product versions to exist in the system simultaneously. Example: VS.80.

Content items can exist in the MTPS in many different
languages and translations. For example, the documentation for the System.Xml.XmlWriter
class is available in both
English and in
German. Locales are of the form defined by the System.Globalization.CultureInfo
class (but case insensitive). Example: de-DE.

A component of a content item. Can be in an XML or binary
format. A document has a type that is either primary,
common, feature, or
image. A document has a format that is specific to
the type. Some document types also have a name.

Fragment of the table-of-contents site navigation. One single fragment contains
one root element and a set of children one level deep. Using a hierarchical TreeView
representation for reference, there exists a fragment for each level on each
branch of the TOC.

Feature documents may contain auxiliary information that complements a content item.
Examples might include user rating information or items related to this page. Feature documents are opaque to
the system. No feature document formats are defined at this time.

When requesting a content item from the MTPS Content Service, a client must specify
which document types and formats they are requesting. Summary information will always
be returned for all document types and formats, but as individual documents may
be quite large, only the contents of those documents matching a requested document
descriptor will be returned.

Version is optional. If version is not specified, the latest version is assumed. Locale, however, is required.
Failure to specify locale will result in a partial match.

Note that if the request contains a content URL and the URL contains version and/or
locale information, and the request also contains version and/or
locale information, then the version/locale in the request itself override the version/locale
in the URL.

Available version and locale information. If other versions
and locales exist that have the same
content
key
as the requested item, a list of these available versions and locales
are returned.

Documents. Summary information for all available documents
is always returned. Additionally, if any documents match the
requested document descriptors in the request, their full contents are also
returned.

If the content key provided in the
request identifies an existing content item,
but the specified version and locale
are not present (or version is not specified and the specified locale is not present),
there is a partial match. In this case, only two things are returned:

Identity information. This includes the short ID, GUID, and
alias (if one exists) of the matched content item.

Available version and locale information. A list of any other
versions
and locales that exist that have the same
content key
as the requested item is returned.

If the sample request above were only a partial match, the response might look as
follows:

Note that no documents are returned - basically just the
various content identifiers and the available versions and locales. Generally the
correct action in response to a partial match will be to select one of the available
versions and locales, and then to retry the request. That should result in an
exact match.

No Match

Faults

When a problem occurs, a SOAP fault of the appropriate version (1.1 or 1.2) is returned.
The faultstring (SOAP 1.1) or Reason/Text (SOAP 1.2) element
of the fault will contain a human-readable, English message describing the error
which has occurred. The detail element of the fault will contain MTPS-specific
information about the error, in the form of a mtps:mtpsFaultDetail
element. The formal schema for that element can be found in the
WSDL document. Here is a brief description of each of the elements:

Element

Description

eventId

A code describing the error. See table below.

source

The source of the error. Always "GetContent".

helpLink

The URL of a webpage containing helpful information about the error and how to resolve
it.

Sample C# Client Code

The below samples demonstrate the use of the MTPS Content Service. They assume that
a proxy has been generated via "Add Web Reference" in Visual Studio 2005, and that
using statements have brought in the namespaces System, System.Web.Services.Protocols,
System.Xml, System.Xml.Serialization, and whatever namespace you assigned to your
proxy when running "Add Web Reference".

// Create the request object
getContentRequest request = new getContentRequest();
// Assign the URL, version, and locale
// Note that the URL specifies a version and a locale
request.contentIdentifier = "http://msdn2.microsoft.com/eak978d4(de-de,VS.70).aspx";
request.locale = null;
request.version = "VS.80";
// Create the proxy and set the SOAP version
ContentService proxy = new ContentService();
proxy.SoapVersion = SoapProtocolVersion.Soap11;
// Call the web service
getContentResponse response = proxy.GetContent(request);
Console.WriteLine(response.contentId); // eak978d4
// Note that the request.version overrides the version embedded in the URL
Console.WriteLine(response.version); // VS.80
// But because request.locale was null, the locale from the URL is used
Console.WriteLine(response.locale); // de-de
// Two common documents are returned
Console.WriteLine(response.commonDocuments.Length); // 2
// The first common document contains search info
Console.WriteLine(response.commonDocuments[0].commonFormat); // MTPS.Search
// No contents were requested, so we only get summary info like format
Console.WriteLine(response.commonDocuments[0].Any.Length); // 0
// One other version/locale is available (German)
// The first version/locale is the one we passed in
Console.WriteLine(response.availableVersionsAndLocales.Length); // 2
Console.WriteLine(response.availableVersionsAndLocales[0].locale); // en-us
Console.WriteLine(response.availableVersionsAndLocales[0].version); // VS.80
Console.WriteLine(response.availableVersionsAndLocales[1].locale); // de-de
Console.WriteLine(response.availableVersionsAndLocales[1].version); // VS.80

GetNavigationPaths Operation

Description

Navigation path data - sometimes referred to as Table of Contents (TOC) information despite
the fact that it is more broadly useful than simply providing a TOC - is somewhat non-intuitive
in structure. Navigation path data for a content item is not stored
within the content item itself. Rather, there is an entirely separate hierarchy of content
items that describe the navigational struture. These content items are easily distinguished
by the presence of an Mtps.Toc document. Mtps.Toc documents contain a
description of a content item and its immediate children, as well as
content keys for the Mtps.Toc documents of those children. Using this
information, it is possible to traverse the entire navigation structure, but it would be
highly inefficient.

The GetNavigationPaths operation allows a client to request all the possible navigational
routes between two topics in a single round trip. Note that more than one route may exist
between two topics, as the TOC may list the same topic in multiple places.

Request

The formal definition of the request can be found in the WSDL (available
here). Here is an sample of what a request might look like:

The root identifies the content item that is the start of the requested navigation
paths. The target identifies the content item that is the endpoint of the requested
navigation paths. Root should be a navigational-type item. Target should be a content-type item, not a navigational-type item. That is, root should refer to an item that has
a document of type Mtps.Toc, while target should refer to an item that has a document
of type Mtps.Xhtml.

The most commonly used root will be the topmost node in the TOC tree. This node
has a short ID of ms310241 and a version of MSDN.10.

A navigationPathNode contains a navigationNodeKey, a contentNodeKey, a title, and a
boolean value indicating whether or not it is a phantom node.

Title is a string containing descriptive text for that node in the navigation path.

The navigationNodeKey and contentNodeKey are both navigation keys, exactly like root
and target in the request.

The distinction between navigationNodeKey and contentNodeKey requires some explanation
of the way navigation data is structured in the MTPS system. For each node in the
table of contents (TOC), there are actually two content items:
one for the TOC node itself, and one for the corresponding content. On the
MSDN website, these correspond to the currently selected node in the left-hand
navigation tree, and the content that appears in the main area of the window. This
degree of separation is necessary because a particular content item could actually
appear in two locations in the TOC.

To reflect this structure, two content keys are returned
for each navigationPathNode. The navigationNodeKey identifies the TOC item itself.
One could, for example, use this key with the GetContent operation
to retrieve the Mtps.Toc document that lists all the children of this TOC node.
The contentNodeKey, on the other hand, identifies the content item to which this
TOC node operates. For example, if the current node is the TOC entry for a class,
the contentNodeKey might identify the content item containing the Mtps.Xhtml document
with overview information for the class.

Phantom nodes are a byproduct of the way navigational data is structured within
MTPS. Essentially, they are "placeholder" navigational nodes that the system must
interject. A node is a phantom node if the the <isPhantom> element in a <navigationPathNode>
has a value of "true". In almost all cases, the correct way to handle phantoms is
to skip them - to process as if the phantom node were not returned at all.

Notes on Selected Document Formats

The Mtps.Xhtml primary document is the main document type in MTPS. It holds
the XHTML content of a content item. This XHTML is generally compliant with
the W3C’s Modular XHTML 1.1 standard. Because of the large amount of legacy
content in the system, there are instances where complete compliance was not
possible, but content is always well-formed XML. In most cases it is also
standards-compliant.

It is important to note that the XHTML MTPS manages is “presentation-free”.
That is, the XHTML contains no script, styles, or other artifacts that would
control the look and feel of the rendered content. This allows the XHTML to
be used in many different contexts by having styling applied at runtime, after
the document is retrieved. The Mtps.Xhtml document does, however, contain
some extension elements (easily detectible by the fact that they are not in
the XHTML namespace) to enable certain behaviors on the MSDN2 website. If
processing these extra elements would cause problems for your application,
you can always use the Mtps.Failsafe primary
document instead. When available, it is an equivalent to the Mtps.Xhtml document
that contains only XHTML elements.

Some of the common extension elements used in Mtps.Xhtml documents are listed
in the following table. The "mtps" prefix indicates a namespace URI of
http://msdn2.microsoft.com/mtps.

Element

Description

mtps:CodeSnippet

Contains a chunk of code. This element may have a Language
attribute indicating the language in which the code is written.
Language might also have a value of "None" indicating that
it is in no particular programming language. For instance, an XML
sample common to all code snippets in a document may have a
Language of "None".

mtps:CollapsibleArea

As the name implies, indicates a region of the document intended to be
collapsible. May have a Title attribute containing the title
of the region.

mtps:InstrumentedLink

Represents a hyperlink. The NavigateUrl attribute will contain
a URL (usually an asset ID) that is the target
of the link.

mtps:KTableControl

TODO: I don't think I really understand what this thing is supposed to do.

The Mtps.Failsafe primary document format is meant to serve as an alternative to the
richer Mtps.Xhtml. Mtps.Failsafe contains an XHTML document that contains none of the
MTPS extensions present in the Mtps.Xhtml format, and as such may be easier for some
consumers to work with.

This XHTML is generally compliant with
the W3C’s Modular XHTML 1.1 standard. Because of the large amount of legacy
content in the system, there are instances where complete compliance was not
possible, but content is always well-formed XML. In most cases it is also
standards-compliant.

As described above in the documentation for GetNavigationPaths,
the Mtps.Toc primary document format is used to express the navigational structure
of content items in MTPS. This is an example of an Mtps.Toc document:

The topmost Node element represents the content item of interest. SubTree,
SubTreeVersion, and SubTreeLocale combine to form a contentKey
for the content item containing
this Mtps.Toc document, and as such are usually not very interesting.
Target, TargetLocale, and TargetVersion, however combine to form a content
key for the content item containing the Mtps.Xhtml document associated with this
navigation node.

Each of the subordinate Node elements represents a navigational child of the
topmost element. Each of them has Target, TargetLocale, and TargetVersion attributes
with the same semantics - they identify the associated content item. SubTree, SubTreeVersion,
and SubTreeLocale may or may not be present, depending on whether that node itself
has child nodes. If so, these attributes combine to identify a content item with an
Mtps.Toc document one level farther "down" the tree.

The semantics of Title are fairly obvious.

The Description attribute is not used and will always be empty.

The IsPhantom attribute indicates whether this node is a navigational phantom. Phantoms
are documented above.

The Mtps.Links document is a convenience addition to any content item whose primary document
contains links by asset ID. It is a straightforward XML format mapping
asset IDs to short IDs, content GUIDs, and
content aliases (if extant). This information is useful to
applications wishing to normalize to on identifier form, or for applications wishing to
translate from asset IDs to short IDs for use in calls to GetNavigationPaths.