SharePoint 2013 & Office 365 APIs & Development Options for Accessing Data
SharePoint 2013’s APIs allow apps, as well as other elements, to connect and integrate with SharePoint’s core features.
EPC Group’s development teams use APIs, as shown in the image below, provide apps their ability to view content or integrate with a workflow or even perform searches.
For example, if you were developing an app for a business intelligence initiative, SharePoint 2013’s APIs would allow your app to connect to SharePoint’s BCS and other elements in a secure manner to access specific data.
SharePoint 2013 APIs can really initially be put into 3 major “buckets” to help better understand their overall capabilities which are:
- Server Side Object Model
- Client-Side Object Model
- REST APIs
Server Object Model
The sever object model in SharePoint 2013 is the largest API set and it covers all features and functionality from both an administrative perspective and for an end user. The server object model’s core assembly is Microsoft.SharePoint.dll which is installed in the Global Assembly Cache (GAC).
The server object model in SharePoint 2013, for example, can be utilized to create server side utility application or even be used to create Timer Job services to run in the background and is extremely useful in modifying list items, performing searches, modifying and\or manipulating permissions or assisting with business continuity elements with backup and restore.
The Server Object Model’s Most Utilized Classes
|Server Object Model||SharePoint Object|
Client-Side Object Model (CSOM)
The client-side object model (CSOM) updates, retrieves, and manages data in SharePoint 2013 in it is available in several different forms to support many of SharePoint 2013’s core capabilities, as shown in the image below. The CSOM provides for:
- .NET Framework redistributable assemblies
- Office 365 API Tools
- Silverlight redistributable assemblies
- REST APIs
- Windows Phone assemblies
Overview of underlying interactions in CSOM within SharePoint 2013
Office 365 API Tools
Microsoft has recently introducing the next step in the evolution of our Office 365 platform by delivering the “preview” release of the Office 365 API tools, as shown in the image below.
This continues to extend the platform and will open up a more possibilities around the hybrid cloud with the ability to not only access SharePoint 2013 on-premises but also extends the platform in Office 2013 by adding the ability for both sites and native applications to consume Office 365 data.
Both of these web applications as well as native applications running on Windows 8, iOS, Android, and other device platforms will be able to consume Office 365 data by using REST APIs and standard OAuth flows.
Screen shot of the new Office 365 API Tools
Note: This preview release of Office 365 API Tools supports a limited number of SharePoint, Exchange, andWindows Azure Active Directory (AD) data sources.
The Office 365 APIs, are shown in the image below, are part of a platform that is built on an entirely new Windows Azure AD and will provide for the more seamless identity management that is so critical to brining more compliance and governance around these environments.
There has also been an updated set of tools in Visual Studio that full be developed in parallel so that the overall application lifecycle management as well as future release management components such as Team Foundation Server will be able to server all data sources and tenants.
The REST APIs are very straightforward and easy to use and allow for a platform agnostic development approach.
You are able to access resources utilizing REST capabilities in SharePoint 2013 by constructing a RESTful HTTP request, using OData, which corresponds to the desired client object model API. An example of this would be, “Client object model method,”
- REST endpoint:
The endpoints in the SharePoint 2013 REST service correspond to the types and members in the SharePoint client object models. The utilization of these HTTP requests allows for the use of these REST endpoints to perform typical CRUD (e.g. create, read, update, and delete) operations against SharePoint entities like SharePoint sites or lists.
The URI (e.g. Uniform Resource Identifier) for these REST endpoints closely mimics the API signature of the resource in the SharePoint client object model as the main entry points for the REST service represent the site collection and site of the specified context for which is submitted.
To provide an overview of this, a specific site collection can be access by using the following:
If you are wanting to access a specific site, you would do so by using the following:
The server always represents the name of the server and the site represents the name of the site or the path to the specific site. By using this as a baseline, you can then construct more specific REST URIs by utilizing the object model names of the APIs from the client object model separated by a forward slash (/).
The REST APIs and OData in SharePoint 2013
REST APIs in SharePoint 2013 are now compatible with OData (e.g. Open Data Protocol), the industry standard for creating and consuming data APIs.
The official reference for OData as well as to track updates regarding this industry standard can be found at the following link:
OData’s official description, in essence, states that OData builds on core protocols like HTTP and commonly accepted methodologies like REST that result is a uniform way to expose full-featured data APIs.
In term of SharePoint 2013, OData is a protocol for interacting with RESTful web services and was released under Microsoft’s open specification promise and works on top of standard HTTP using HTTP GET, POSTS, PUT, and DELETE verbs and returns standard ATOM or JSON formatted results.
RESTful web services are basically those services or applications that conform to REST constraints and any service that does not conform to the required constraints should not be considered RESTful.
There is a very strong focus on resources within RESTful web services and that they be simple for a developer to utilize. There are four principles that these services should follow which are as follows:
- Utilize HTTP methods appropriately
- Expose data in a directory structure
- Be stateless
- Transfer either XML or JSON formatted results, as shown in the image below:
REST and Search in SharePoint 2013
The new Search capabilities in SharePoint 2013 include a Search EST service that you can utilize to add additional search features and functionality to your organization’s client applications as well as your mobile applications that support REST web requests.
This capability allows you to use the Search REST service to submit Keyword Query Language (KQL) or FAST Query Language (FQL) queries in apps for SharePoint, mobile apps, and remote client apps and in addition the new Search REST service also supports both HTTP POST and HTTP GET requests.
For GET requests, you would construct the URI for query GET requests to utilize the Search REST service by using the following:
The GET requests specifies the query parameters in the URL and can utilize two different options for constructing GET requests as detailed below:
For POST requests, you would construct the URI for query POST requests to utilize the Search REST service by using the following:
You should utilize POST requests whenever you:
- Have concerns about the length of your URL due to issues you may experience regarding URL length restrictions that may be experienced with a GET request.
- Are not able to specify the query parameters via a simple URL such as those in pass parameter values that contain a complex type array as there is added flexibility around the construction of POST requests.
You must ensure that whenever a call is made to the Search REST service, the specific query parameters are included with the request as these query parameters are used to construct the underlying SharePoint search query.
These query parameters are specified in different manners between GET and POST requests as follows:
- GET requests specify the query parameters in the URL
SharePoint 2013 and Office 365 Application Development “From the Consulting Trenches”
This is the third in a series of blog posts by EPC Group on SharePoint 2013, Office 365, and SharePoint Online development strategies and best practices “from the consulting trenches.”
EPC Group’s Nationally Recognized Practice Areas
EPC Group leading SharePoint, Office 365, Infrastructure Design and Business Intelligence Practice areas continue to lead the way in providing our clients with the most up-to-date and relevant information that is tailored to their individual business and functional needs.
Additional “From the Consulting Trenches” strategies and methodologies are covered in EPC Group’s new book, “Sharepoint 2013 Field Guide: Advice from the Consulting Trenches” covering not only SharePoint 2013, Office 365 and SharePoint Online but Information Management, ECM\RM and overall compliance strategies in this ever changing world of “Hybrid IT.”