Choose the right API set in SharePoint
Learn about the several sets of APIs that are provided in SharePoint, including the server object model and the various client object models, and the REST/OData web service.
Factors that determine which API set to use
You can choose from several sets of APIs to access the SharePoint platform. Which one you use depends on the following factors:
- Your existing skills. To a surprising degree, you can create applications in SharePoint without needing to learn a lot about SharePoint programming. You can jump right into SharePoint development if you already have experience in any of the following programming models:
- .NET Framework
- Windows Phone
- Windows PowerShell
- The device on which the code runs. The possibilities include a server in the SharePoint farm, an external server such as a server in the cloud, a client computer, and a mobile device. This topic provides an overview of the various API sets that are provided by SharePoint. Figure 1 shows which sets of APIs can be used to develop each of 13 common SharePoint-related applications. For many applications, you can choose from more than one API.
Figure 1. Selected SharePoint extension types and SharePoint sets of APIs
The following table provides guidance on which set of APIs to use for a selected list of common SharePoint extensibility projects. The remaining sections of this topic describe the various sets of APIs.
|If you want to do this ...||... use these APIs|
|Create an ASP.NET web application that performs CRUD operations on SharePoint data or external data that is surfaced in SharePoint by a BCS external content type, but does not have to call SharePoint across a firewall||.NET Framework client object model, Silverlight client object model, or REST/OData endpoints|
|Create a LAMP web application that performs CRUD operations on SharePoint data or external data that is surfaced in SharePoint by a BCS external content type||REST/OData endpoints|
|Create a Windows Phone app that performs CRUD operations on SharePoint data||Mobile client object model|
|Create a Windows Phone app that uses the Microsoft Push Notification Service to alert the mobile device of events in SharePoint||Mobile client object model and the server object model|
|Create an iOS or Android app that performs CRUD operations on SharePoint data||REST/OData endpoints|
|Create a .NET Framework application that performs CRUD operations on SharePoint data||.NET Framework client object model|
|Create a Silverlight application that performs CRUD operations on SharePoint data||Silverlight client object model|
|Create a custom Windows PowerShell command||Server object model|
|Create a timer job||Server object model|
|Create an extension of Central Administration||Server object model|
|Create consistent branding across an entire SharePoint farm||Server object model|
|Create a custom web part, application page, or ASP.NET user control||Server object model
Important: If the functionality you want to offer customers is not oriented to SharePoint administration at a scope broader than site collection, we recommend that, instead of using the server object model, you create an SharePoint Add-in that includes a remote ASP.NET web application with custom web parts and user controls as needed. See the top two rows of this table.
Server object model
The largest set of APIs is in the server object model of managed classes. At the level of SharePoint Foundation 2013, this object model includes classes and members that enable programmatic control of the basic site and list structure of SharePoint Foundation. Most of these classes are in the Microsoft.SharePoint namespace. In addition, you can extend almost every SharePoint Foundation component by using the server object model, including workflows, alerts, web parts, basic search, and Microsoft Business Connectivity Services (BCS). The server object model also includes an extensive set of APIs enable extensions of the administration and security system of SharePoint Foundation, including backup, farm health and diagnostics, logging, farm and web application management, upgrade, deployment, caching, and Windows PowerShell customization.
At the level of SharePoint, many more classes are added to enable programming of Enterprise Content Management (ECM), user profiles, taxonomy, advanced search, and other features of SharePoint.
You can use LINQ to Objects to query any IEnumerable collection in memory, but a LINQ to SharePoint provider enables direct querying of the lists in the SharePoint content databases. Strictly speaking, this provider is not available with any other set of APIs discussed in this topic; however, there are ways to use LINQ syntax in most of the others.
The assemblies that define the built-in server-side classes are installed to the global assembly cache of each server when SharePoint is installed. When you program against the server object model, your assemblies are installed as farm solutions to the global assembly cache.
Developing new sandboxed solutions against SharePoint is deprecated in favor of developing SharePoint Add-ins, but sandboxed solutions can still be installed to site collections on SharePoint. The assemblies of these solutions remain in the package except when they are actually in use, at which time they are temporarily installed to a folder on the server. For more information, see Where are Assemblies in Sandboxed Solutions Deployed?.
Limitations on when you can use the server object model
Client object models for managed code
SharePoint has three client object models for managed code: .NET, Silverlight, and mobile.
.NET client object model
The SharePoint object model for .NET Framework is used in .NET Framework applications that run on a non-phone Windows client. Any of the following counts as such a client:
- A user's computer
- A server that is external to the SharePoint farm
- A web role or worker role on Microsoft Azure
Almost every class in the core site and list server object model has a corresponding class in the .NET Framework client object model. In addition, the .NET Framework client object model exposes a full set of APIs for extending other features, including some SharePoint features such as ECM, taxonomy, user profiles, advanced search, analytics, BCS, and others.
To improve performance, lines of code written against in the .NET Framework client object model are sent to the SharePoint server in batches where they are converted to server-side code and executed. The queried results, and the new state of all variables, are then returned to the client. You as the developer determine whether a batch runs synchronously or asynchronously. (In a synchronous batch, the .NET Framework application waits for the returned results from the server before continuing; in an asynchronous batch, client-side processing continues immediately and the client user interface (UI) remains responsive.)
You can use LINQ query syntax in your client code to query any IEnumerable object, including SharePoint objects that implement IEnumerable. However, when you do this, you are using LINQ to Objects, not the LINQ to SharePoint provider, so documentation of the latter is not relevant to client-side code.
The assemblies for the .NET Framework client object model must be installed on the client. They are included in a redistribute package that you can obtain on the SharePoint Client Components.
For examples of using the .NET Framework object model, see Complete basic operations using SharePoint client library code.
You can also use the SharePoint REST/OData endpoints in a .NET Framework application. For a comparison of the .NET Framework client object model with the SharePoint REST/OData endpoints, see the section REST/OData endpoints later in this article.
Silverlight client object model
The SharePoint object model for Silverlight is used in Silverlight applications, regardless of where the compiled .xap file is persisted. It may be in an assets library on a SharePoint website, on a client computer, in cloud storage, or on an external server. Typically, a Silverlight application is surfaced in SharePoint in a SilverlightWebPart object. The Silverlight client object model in SharePoint is nearly identical to the .NET Framework client object model, and it includes support for the same extensibility areas. The principal difference is that in the Silverlight version, all batches of commands are sent to the server asynchronously so that the UI of the application remains active.
The assemblies for the Silverlight client object model are persisted on every SharePoint server at %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\15\TEMPLATE\LAYOUTS\ClientBin. They do not have to be installed on the computer that is running the Silverlight application, although you have the option of doing so. Also, you can package them into the .xap file of the application.
Silverlight .xap files can be included in SharePoint Add-ins, including SharePoint-hosted apps. In the latter case, the .xap file is deployed to a library on the app web. (For more information about app webs, see Host webs, add-in webs, and SharePoint components in SharePoint.) This makes a Silverlight application a useful way of including custom SharePoint code in an app, because custom server-side code is not allowed in SharePoint Add-ins. It also enables Silverlight developers to use their existing skills to create SharePoint applications with a minimal learning curve.
You can also use the SharePoint REST/OData endpoints in a Silverlight application. For a comparison of the Silverlight client object model with the SharePoint REST/OData endpoints, see the section REST/OData endpoints later in this article.
Mobile object model
A special version of the Silverlight client object model is available for Windows Phone devices. It includes some additional APIs that are relevant only to telephones, such as APIs that enable a phone app to register for notifications from the Microsoft Push Notification Service. It supports all core SharePoint functionality; however, it does not provide support for any of the non-core extensibility areas that are supported by the other two client object models for managed code. To access those additional areas, use the SharePoint REST/OData endpoints in your mobile app. See the section REST/OData endpoints later in this article.
The assemblies for the mobile object model are persisted on every SharePoint server at %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\15\TEMPLATE\LAYOUTS\ClientBin. You package them into the .xap file of your Windows Phone application.
For more information about using the REST/OData web service, see the node Use OData query operations in SharePoint REST requests; for examples, see the topic Complete basic operations using SharePoint REST endpoints.
Comparing REST/OData programming with client object model programming
|APIs for conditional processing and exception handling||Yes||No||No|
|Availability of LINQ syntax||Yes||No||No|
|Combining list data from different SharePoint web applications||Yes||No||Yes|
|Familiarity to experienced REST/OData developers||No||No||Yes|
WCF Data Services Framework
If you prefer to use LINQ syntax in .NET Framework or Silverlight client applications, SharePoint supports WCF Data Services as a LINQ provider. You can target either the listdata.svc (for list data only) as in earlier versions of SharePoint Foundation, or you can target the same client.svc that supports the OData interface for access to all SharePoint entities in addition to list data. For more information, see Query SharePoint Foundation with ADO.NET Data Services.
Figure 2 illustrates the relationship of the various client APIs, various types of client applications, and SharePoint. The various
_api URLs are the farm-relative URLs for the REST endpoints. For more information, see the topic Learning more about the SharePoint 15 REST service.
Figure 2. Client applications and APIs in SharePoint
Deprecated API sets
Two API sets are still supported in the SharePoint framework for backward compatibility, but we recommend that you not use them for new projects: the ASP.NET (asmx) web services, and direct Remote Procedure Calls (RPC) calls to the owssvr.dll file.
- SharePoint development overview
- Programming models in SharePoint
- SharePoint Add-ins compared with SharePoint solutions
- Use OData query operations in SharePoint REST requests
- Complete basic operations using SharePoint REST endpoints
- Complete basic operations using SharePoint client library code
- Application Lifecycle Management (ALM) APIs
- Query SharePoint Foundation with ADO.NET Data Services