Data access options for apps in SharePoint 2013
Published: July 16, 2012
Learn about the data access options you have when you build apps for SharePoint in SharePoint 2013, including data connectivity options for inbound and outbound data scenarios, and the APIs that are available when you want to access SharePoint data from your app.
Applies to: apps for SharePoint | Office 365 | SharePoint Foundation 2013 | SharePoint Server 2013
In evaluating your data access options for apps for SharePoint, you have to assess your app environment and consider several factors, such as communication between the client and server, and the permission level that is required for your app to perform the required tasks. You also have to evaluate the APIs that are available in the model for apps for SharePoint.
It is hard to imagine an app for SharePoint (or any app for that matter) that does not need to query, store, or manipulate data. In your app, you will frequently have to retrieve and manipulate SharePoint data, such as items in document libraries and lists, metadata, or user profiles. Similarly, you might have scenarios where you need to access data that is exposed by your app from within a SharePoint page or component. The model for apps for SharePoint provides multiple connectivity options and a rich set of APIs for accessing the rich data and services that reside on SharePoint and on the remote app.
As you design your app and plan for data access, you have to make two key decisions:
-
Which connectivity option should I use?
-
What APIs should I use for accessing the data I need?
The following figures summarize the different options that are provided by SharePoint 2013. In the sections that follow, you will examine each option in detail and learn when to use them.
Figure 1 illustrates the options you have for accessing SharePoint data from a remote app. When you are dealing with inbound scenarios, you have to decide whether you want to authenticate and communicate to SharePoint by using (1) OAuth, or (2) the cross-domain library. Then, for the data access API, you must decide between (3) the client object model (JavaScript/.NET client object models), or (4) Representational State Transfer (REST).
Figure 2 shows the options that you have for accessing the data on your remote app from SharePoint. When you are working with outbound scenarios, you have to decide whether you want to use (1) the web proxy, (2) remote event receivers, or (3) the cross-domain library with a custom proxy page to authenticate and communicate with external services or apps. You have to use the available APIs in the remote app to retrieve or manipulate data.
Important
|
|---|
|
For intranet scenarios, you should consider an app-scoped external content type. For more information, see Get started with app-scoped external content types. |
You have to consider several aspects when you work with data in your app. For example, what route is the data using? Is it coming from or going through the server? Is it going through the client? Is it OK to authenticate as the logged-on user? Does the app need elevated privileges? The following sections can help you with these and other questions you may have.
Inbound data connectivity
The following connectivity options are available for inbound scenarios (see Figure 1):
-
OAuth: An open protocol that enables secure authorization in a simple and standard way. OAuth enables users to approve an application to act on their behalf without sharing their user name and password. You can use OAuth with server-side code. It is a good option if you need to run a non-interactive process, or if you need to elevate privileges to other than those of the logged-on user. For information about OAuth, see Authorization and authentication for apps in SharePoint 2013.
-
Cross-domain library: A client-side alternative in the form of a JavaScript file (SP.RequestExecutor.js) hosted in the SharePoint website that you can reference in your remote app as long as they are in the same internet zone. The cross-domain library allows you to interact with more than one domain in your remote app page through a proxy. This is a good option if you prefer your app code to run in the client rather than in the server, or if there are connectivity barriers, such as firewalls, between SharePoint and your remote infrastructure. For more information, see How to: Access SharePoint 2013 data from remote apps using the cross-domain library.
Inbound data connectivity options: Which one should I use?
The following table lists the common requirements and scenarios you might encounter when you are building apps. An x in the column indicates which option—OAuth or cross-domain library—you can use in each case.
|
Requirement/Scenario |
OAuth |
Cross-domain library |
|---|---|---|
|
I use client-side technologies (HTML + JavaScript). |
|
x |
|
I want to use REST interfaces. |
x |
x |
|
There is a firewall between SharePoint and my remote app, and I need to issue the calls through the browser. |
|
x |
|
My app needs to access resources as the logged-on user. |
x |
x |
|
My app needs to elevate privileges to other than those of the current logged-on user. |
x |
|
|
My app needs to act on behalf of a user other than the one who is logged on. |
x |
|
|
My app needs to perform operations only while the user is logged on. |
x |
x |
|
My app needs to perform operations even when the user is not logged on. |
x |
|
Outbound data connectivity
The following connectivity options are available for outbound scenarios (see Figure 2):
-
Web proxy: As a developer, you can use the web proxy exposed in client APIs such as the JavaScript/.NET client object models. When you use the web proxy, you issue the initial request to SharePoint. In turn, SharePoint requests the data to the specified endpoint and forwards the response back to your page. Use the web proxy when you want the communication to occur at the server level. For more information, see How to: Query a remote service using the web proxy in SharePoint 2013.
-
Remote event receivers: You can use remote event receivers to handle events that occur to an item in the app, such as a list, a list item, or a web. These events resemble those in a traditional SharePoint solution, except that they can work with the remote components of the app for SharePoint. For more information, see Handling events in apps for SharePoint.
-
Custom proxy page for the cross-domain library: You can use the cross-domain library to access data in your remote app if you provide a custom proxy page that is hosted in the remote app infrastructure. As the developer, you are responsible for the custom proxy page implementation and must deal custom logic, such as the authentication mechanism, to the remote app. Use the cross-domain library with a custom proxy page if you want the communication to occur at the client level. For more information, see How to: Create a custom proxy page for the cross-domain library in SharePoint 2013.
Outbound data connectivity options: Which one should I use?
The following table lists the common requirements and scenarios you might encounter when you are building apps. An x in the column indicates which option—web proxy library or cross-domain library with a custom proxy page—you can use in each case.
|
Requirement/Scenario |
Web proxy |
Cross-domain library with custom proxy page |
Remote event receivers |
|---|---|---|---|
|
I use client-side technologies (HTML + JavaScript). |
x |
x |
|
|
I cannot add pages or components to the remote app or service. |
x |
|
x |
|
I want to use REST interfaces. |
x |
x |
x |
|
I want to use the JavaScript CSOM. |
x |
x |
|
|
I want to use the .NET CSOM. |
x |
|
x |
|
There is no direct connectivity between the SharePoint server and my app. I need to issue calls through the browser. |
|
x |
|
|
My app needs to access resources as the logged-on user. |
x |
x |
|
The following API choices are available when you want to access SharePoint data from your app:
-
Representational State Transfer (REST): For scenarios in which you need to access SharePoint entities from client technologies that do not use JavaScript and are not built on the .NET Framework or Silverlight platforms, SharePoint 2013 provides an implementation of a REST web service that uses the Open Data (OData) protocol to perform CRUDQ (Create, Read, Update, Delete, and Query) operations on SharePoint list data. In addition, nearly every API in the client object models has a corresponding REST endpoint. This enables your code to interact directly with SharePoint by using any technology that supports standard REST capabilities. To use the REST capabilities that are built into SharePoint 2013, your code constructs a RESTful HTTP request to an endpoint that corresponds to the desired client object model API. The client.svc web service handles the HTTP request and serves a response in either Atom or JavaScript Object Notation (JSON) format. To learn more about REST in SharePoint, see Programming using the SharePoint 2013 REST service.
-
.NET Framework client object model (.NET client OM): Almost every class in the core site and list server-side object model has a corresponding class in the .NET Framework client object model. In addition, the .NET Framework client object model also exposes a full set of APIs for extending other features, including some SharePoint Server 2013-level features such as ECM, taxonomy, user profiles, advanced search, analytics, BCS, and others. To learn more about client-side object models, see API sets of SharePoint 2013 Preview.
-
JavaScript client object model (JS client OM):SharePoint 2013 provides a JavaScript object model for use in either inline script or separate .js files. It includes all the same functionality as the .NET Framework and Silverlight client object models. The JavaScript object model is a useful way of including custom SharePoint code in an app, because custom server-side code is not allowed in apps for SharePoint. It also enables web developers to use their existing JavaScript skills to create SharePoint applications with a minimal learning curve. To learn more about client-side object models, see API sets of SharePoint 2013 Preview.
When you want to access data in your app from SharePoint, you have to use the APIs that the app provides.
-
Authorization and authentication for apps in SharePoint 2013
-
Three ways to think about design options for apps for SharePoint
-
Important aspects of the app for SharePoint architecture and development landscape
-
Host webs, app webs, and SharePoint components in SharePoint 2013
-
How to: Access SharePoint 2013 data from remote apps using the cross-domain library
-
How to: Create a custom proxy page for the cross-domain library in SharePoint 2013
-
How to: Query a remote service using the web proxy in SharePoint 2013
