APIs and Development Options for Data and Resources

SharePoint 2013’s APIs allow apps, as well as other elements, to connect and integrate with SharePoint’s core features.

The development team at EPC Group uses APIs, as shown in the image below, that 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

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
• JavaScript library
• Silverlight redistributable assemblies
• REST APIs
• Windows Phone assemblies

The following image is an overview of underlying interactions in CSOM within SharePoint 2013:

Office 365 API Tools

Microsoft has recently introducing the next step in the evolution of the 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.

The following is a 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, and Azure Active Directory (AD) | (rebranded Windows Azure Acttive Directory) data sources.

The Office 365 APIs, are shown in the image below, are part of a platform that is built on an entirely new Azure Active Directory (i.e. 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.

REST APIs

The REST APIs are very straightforward and easy to use and allow for a platform agnostic development approach.

Each query that is submitted is done via a unique URL and the returned results are able to be cached by proxy servers. The REST APIs are easier to utilize than a SOAP-based Web service and provide for higher productivity when using JavaScript and jQuery.

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,”

• List.GetByTitle(listname)
• REST endpoint:
• http://server/site/_api/lists/getbytitle('listname')

The client.svc service handles the HTTP request and serves the appropriate response in either Atom or JSON (e.g. JavaScript Object Notation) format and the client application must then parse that response.

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:

• http://server/site/_api/site

If you are wanting to access a specific site, you would do so by using the following:

• http://server/site/_api/web

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:

http://www.odata.org

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:

• /_api/search/query

The GET requests specifies the query parameters in the URL and can utilize two different options for constructing GET requests as detailed below:

• ttp://server/_api/search/query?query_parameter=value&query_parameter=value

or

• http://server/_api/search/query(query_parameter=value&query_parameter=<value>)

For POST requests, you would construct the URI for query POST requests to utilize the Search REST service by using the following:

• /_api/search/postquery

The POST requests are passed via the query parameters in the request in JSON (JavaScript Object Notion) format and the HTTP POST version of the Search REST service supports all the parameters supported by the HTTP GET version.

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
• POST requests pass the query parameters in the body in JavaScript JSON format.

SharePoint 2013 and Office 365 Application Development "From the Consulting Trenches"

I will continue this series of posts from EPC Group on SharePoint 2013, Office 365, and SharePoint Online development strategies and best practices “from the consulting trenches.”