Is there any documentation on TFS Web Services?

Question

I am looking for any information on the Microsoft TFS Web Services. First I know accessing the Microsoft TFS Web Services directly is not supported and Microsoft provides no documentation for doing this. Therefore I am not expecting any Microsoft support or assistance here.

I know all about the .Net API available for TFS which only works on Microsoft Operating Systems. I have used these many times on Windows, however I need to do non-Windows work to access TFS, I cannot use .Net and I cannot use a Proxy (or "shim") to be installed on a Windows computer to provide Web Services for the .Net API.

I know Teamprise reversed engineered the web services and they successfully used this knowledge to make a very good cross platform Team Explorer and command line implementation in Java to access TFS. So good in fact they were purchased by Microsoft and the product rebranded and rereleased as Microsoft Visual Studio Team Explorer Everywhere.

I have also tested the .Net API against Mono on several non-windows platforms and they are not compatible. The initial NTLMv2 authentication is using calls not supported by Mono. They appear to be, understandably, making Win32 specific calls for NTLMv2 support.

Therefore before I go to the trouble of reverse engineering them for myself, and dealing with NTLMv2 to do it. I am hoping that there is some hidden or buried information on the web that someone may have documented some portion of the web services for TFS from 2005, 2008 and/or 2010.

Please no comments or posts about how this is not recommended or supported by Microsoft, that I should find a way to use the .Net API, or suggesting the Proxy/Shim is the best solution. I am fully aware of the Microsoft's official stance on this, and what the supported workarounds would be.

Answer 1

I'm not aware of any documentation for the TFS web services, but I can share some tips on calling them.

The NTLM authentication you mention is really a separate layer: you must authenticate to IIS before it lets you call TFS web services. I'm not aware of any Open Source software that will do NTLM auth for you, but TFS 2010 makes it easy to enable "Negotiate" authentication (SPNEGO on Wikipedia, Authentication by using Kerberos Ticket on MSDN). Negotiate supports both NTLM and Kerberos subsystems, and there may be some existing software you can use to drive it using the system's Kerberos libraries (I think curl does it). If you had to build it yourself, it would probably be easier to go the Negotiate-with-Kerberos route.

Once you're authenticated, you can start calling services. Start by pulling down the WSDL for each service (stick a "?wsdl" suffix on each endpoint URI). Hop over to where TFS is installed and explore the web application directory for endpoints. There are several versions of some endpoints for back compat with TFS 2005 and 2008, but usually new versions are not redundant (they add new stuff). You might have a favorite SOAP client library already (there are many for Java), but I can't really recommend any because we wrote our own at Teamprise.

Services like version control, build, and common structure are easy to discover via WSDL. Most the operations have obvious names, but the complex type fields are often super-abbreviated. The best way to figure which methods to call when is to watch the VS TFS client or TEE with Fiddler or Wireshark or some other HTTP inspection program. TFS VC does do things like file uploads/downloads outside the web services (watch a network trace to see the multi-part MIME upload process and be sure you're sending the right values if you implement this).

A note of caution on the work item tracking web service: this one is going to be extremely hard to master. The WIT design involves the client pre-querying the server for large amounts of schema-less metadata, which is saved on the client (but refreshed incrementally as more web service calls are made). This metadata drives all the client side behavior about work items (what fields are in a work item type, the type of a field, which values are allowed in fields, the rules that run when they change, etc.) and it will take a long time and serious study to build the client behavior to bring a work item to life. Once you have a work item, sending it to the server for update via web services is easy.

It's a lot of work, but it's possible to do incrementally, for example, if you only need some VC features. The TEE team is working on making access from other platforms easier. Please contact Martin Woodward ([email protected]) if you have any questions or suggestions in this area.

Answer 2

There is a Java version of the TFS SDK that will run on Linux, Mac, and Windows. It is the SDK that Teamprise uses.

http://blogs.msdn.com/b/bharry/archive/2011/05/16/announcing-a-java-sdk-for-tfs.aspx

Coding directly against the TFS webservices is not supported (even though people have done it). MSFT could break the interface without letting you know in a service pack or other hotfix. Sometimes there aren't other options, but if the Java SDK works for you, I'd try to use that first.