Talk to SharePoint Through Its Web Services

Introduction

Microsoft Office 2003 is very tightly integrated with SharePoint by utilizing its Web services. Windows SharePoint Services comes with sixteen different Qeb services. SharePoint Portal Server 2003 supports an additional five Web services. The Web services provided by SharePoint do provide a vast array of features, but not all SharePoint features are accessible through them. If required, you can build your own Web service on top of SharePoint, thus leveraging the managed SharePoint server API itself. The Web service interfaces make it very easy to integrate SharePoint capabilities right into your application.

This article is not a detailed documentation of every Web method and Web service provided by SharePoint. It is rather an introduction to its capabilities and how to use them. You can download the Windows SharePoint Services SKD or the SharePoint Portal Server SKD for a complete reference of all Web services and also of the server API itself. Please refer to this article for a guide of how to install and administrate SharePoint or this article for a guide of how to use and customize SharePoint portals.

How to Add a Windows SharePoint Web Service Reference

You can add a Web reference to each SharePoint Web service through your Visual Studio .NET IDE. In your Solution Explorer, right-click on your project and select “Add Web Reference” from your popup menu. The table below shows the URLs to use for each Web service provided by WSS. Enter the URL to the Web service and click the Go button. This will show you a summary of all available Web methods in the dialog box. Next, enter the name of the Web reference and then click Add Reference.

WSS Web Services Web Reference
Administration Service http://<server-url:port-number>/_vti_adm/admin.asmx
Alerts Service http://<server-url>/_vti_bin/alerts.asmx
Document Workspace Service http://<server-url>/_vti_bin/dws.asmx
Forms Service http://<server-url>/_vti_bin/forms.asmx
Imaging Service http://<server-url>/_vti_bin/imaging.asmx
List Data Retrieval Service http://<server-url>/_vti_bin/dspsts.asmx
Lists Service http://<server-url>/_vti_bin/lists.asmx
Meetings Service http://<server-url>/_vti_bin/meetings.asmx
Permissions Service http://<server-url>/_vti_bin/permissions.asmx
Site Data Service http://<server-url>/_vti_bin/sitedata.asmx
Site Service http://<server-url>/_vti_bin/sites.asmx
Users and Groups Service http://<server-url>/_vti_bin/usergroup.asmx
Versions Service http://<server-url>/_vti_bin/versions.asmx
Views Service http://<server-url>/_vti_bin/views.asmx
Web Part Pages Service http://<server-url>/_vti_bin/webpartpages.asmx
Webs Service http://<server-url>/_vti_bin/webs.asmx

Setting the Web Service User Credentials

The SharePoint Web services only accept calls from existing SharePoint users and do also enforce access security. Import the System.Net namespace into your project and then use the NetworkCredential class to set the user credential to use for the Web service call. Here is a code snippet:

public static XmlNode VersionsGetVersions(string SharePointHost,
                                          string UserName,
                                          string Password,
                                          string Domain,
                                          string FileName)
{
   // proxy object to call the Versions Web service
   Versions.Versions VersionsService = new Versions.Versions();

   // the user credentials to use
   VersionsService.Credentials = new NetworkCredential(UserName,
                                                       Password,
                                                       Domain);
   VersionsService.Url = SharePointHost + "_vti_bin/Versions.asmx";

   // gets the file versions
   XmlNode Result = VersionsService.GetVersions(FileName);

   // dispose the Web service object
   VersionsService.Dispose();
   return Result;
}

For example, first you create an instance of the Versions Web service. Then, you assign a new instance of the NetworkCredential class to the Credentials property on the created Web service object. You pass along the user name, password, and the user’s domain name to the NetworkCredential object. Next, you set the Web service URL, which might very well be different from the one used when you created the Web reference. Finally, you invoke the desired Web method, in the code snippet above the GetVersions() Web method. The Web method takes a file name and returns an XML document with all available versions of this file. (Document libraries can have versioning enabled and then keep a history for each version.) At the end, you call Dispose() on the Web service object to free up any underlying unmanaged resources.

If the user does not exist in SharePoint or does not have the permission to perform the operation, a WebException is thrown by SharePoint. The returned HTTP status is 401, which means unauthorized request. There are some inconsistencies across all Web services. For example, some Web methods take an XML string as input while others take an XmlNode as input. Most Web methods return the result as XmlNode whereas others return an XML string and while others again return complex data structures. But, after you get used to these inconsistencies, it is very easy to use these Web services and integrate SharePoint capabilities right into your application.

A Summary of the “Windows SharePoint Services” Web Services

The following table provides an overview what capabilities are exposed through the “Windows SharePoint Services” Web services. Each Web service is targeted towards a specific area although there is some overlap. You, for example, can use the Lists Web service and the Site Data Web service to work with SharePoint lists, or you can use the Site Data Web service and the Webs Web service to work with sites meta-data and sub-sites. Please refer to the attached “SharePoint web service browser” sample application, which provides a windows form interface to browse all Web services and all its Web methods. It enables you to play with each Web method or Web service and better understand its usage. It also displays the detailed SDK help page to each Web service and Web method.

WSS Web Services Description
Administration Service This Web service provides administrative capabilities like creating a new top-level site, deleting a top-level site and getting the list of available languages.
Alerts Service Provides access to the list of active alerts and allows to delete active alerts.
Document Workspace Service This Web service is used to manage Document Workspace sites. It allows you to create new document workspaces, delete document workspaces, create new sub-folders, delete sub-folders, and so forth.
Forms Service Each list has forms associated which are used to display list items, create new list items, and update or delete existing list items. This Web service allows to get the collection of forms associated with a list and then get detailed information about each form.
Imaging Service SharePoint has picture libraries that users can use to manage pictures. This Web service allows to upload pictures, download pictures, create new folders, delete folders and pictures, and the like.
List Data Retrieval Service Allows you to run XPath like queries against a list.
Lists Service This Web service is used to work with lists and list data. You can obtain the collection of lists, add new lists, remove lists, add new list attachments, remove attachments, and so on.
Meetings Service This Web service is used to work with Meeting Workspaces. You can create a new Meeting workspace, remove an existing Meeting workspace, add new meetings, add new meetings using ICal files, and so forth.
Permissions Service Sites and lists have permissions assigned to them. This Web service is used to obtain the permissions assigned to a list or site, add new permissions, and update or removing existing permissions.
Site Data Service The Site Data Web service can be used to return meta-data about a site or list, get the collection of lists, get the attachments for a list item, get the collection of items in a list, and so on.
Site Service This Web service can be used to return the list of site templates. When you create a new site using the Administration Web service you need to specify the site template name to use that you can obtain through this Web service.
Users and Groups Service This Web service is used to work with users, site-groups and cross-site groups. You can add, update or remove users, site-groups, and cross-site groups. You can also add users or cross-site-groups to a site-group.
Versions Service Document Libraries and Picture Libraries can have versioning enabled, which stores a copy of every single file version. This Web service can be used to get the list of available versions, delete versions, and also restore a file version.
Views Service Lists have views associated that define what fields are shown, what filtering and sorting is applied, what grouping is applied, and so on. This Web service is used to work with list views. You can get the collection of views, add new views, remove views, update the Html code used to display a view, and the like.
Web Part Pages Service Web Parts are objects that you can place on Web part pages. This Web service is used to work with Web parts and Web part pages. You can get the list of Web parts on a page, you can add or remove Web parts, and so forth.
Webs Service This Web service is used to work with sites and sub-sites. You can get the list of list-templates, get meta-data about a sub-site, get the list of sub-sites, and so on.

More by Author

Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Must Read