INTRODUCING REMOTE APIS IN SHAREPOINT 2013
When SharePoint first started gaining
traction with users all across the world around the year 2002, the
product was very different than the developer friendly platform it is
today. Initially, SharePoint wasn’t built with developers in mind. It
didn’t offer good extensibility points or customization techniques,
which lead to people’s customizing SharePoint in unsupported and often
fragile ways. Microsoft heard loud and clear from people all over the
world that they wanted to be able to do things such as change the
branding and make templates for parts of SharePoint. As a result,
releases such as SharePoint 2007 and the move from ASP to ASP.NET
represented great steps forward, and new options for extensibility
emerged. People were able to build Web parts and had access to
SharePoint’s Server-Side Object Model (Server OM) that allowed them to
call into SharePoint data and perform operations programmatically.
These features enabled developers to build solutions of all kinds.
However, this code that leveraged the Server OM ran as part of
SharePoint’s processes. The code would load within SharePoint, which
made it vital to ensure that it was of high quality; otherwise, the
code could adversely affect SharePoint. Issues such as high memory
consumption and high CPU load became prevalent. In fact, Microsoft has
often acknowledged that many of the critical support issues customers
raised with them had their root cause identified as issues with custom
code in the SharePoint process. This was, of course, not a good thing
for SharePoint’s image and reputation. Matters were further complicated
by the fact that, at times, the Server OM was hard to use. For example,
developers needed to know how and when to dispose of objects correctly.
Not doing so could lead to high memory consumption. Conversely,
disposing of the wrong thing could cause crashes.
Additionally, SharePoint has for some time
provided a set of SOAP-based Web services that enable users to do some,
but by no means all, of the same things the Server OM provided. These
Web services revolved around sending and receiving a SOAP-formatted XML
payload to and from SharePoint. These services have not stood the test
of time well though. They are bulky and cumbersome and have been in
dire need of an upgrade.
In the SharePoint 2013 release, those same Web
services exist for backward compatibility. In fact, in SharePoint 2013
Microsoft has signaled it is deprecating these older SOAP-based
services, which means you are unlikely to see them in future releases.
Deprecating is a warning to stop using these services and to start
thinking about shifting your code to the newer, more modern APIs.
Because the Server Object Model and the SOAP Web
services are the two main APIs available for programmatically
integrating with SharePoint, and because both of these options have
significant drawbacks in their approach given modern recent
developments in API and protocol design, SharePoint 2013 addresses
these issues head-on. The new release of SharePoint provides a new,
consolidated set of APIs for developers based on newer Web standards
and modern coding practices, and targets integration scenarios that are
the most prevalent and common. For developers who build solutions that
integrate with SharePoint this is good news.
CLIENT-SIDE OBJECT MODEL (CSOM) BASICS
In SharePoint 2010 Microsoft took the
first steps toward providing better remote API options to developers
with the introduction of the Client-Side Object Model, or CSOM. The
CSOM came in three varieties:
- Managed Code (.NET)
- ECMA Script (also known as JavaScript)
- Silverlight
This model provided developers with the ability
to access some functionality of SharePoint from remote code
applications. For example, a Silverlight application running on a Web
page could call back into SharePoint and retrieve data, or another
system written in a .NET language could do the same. In fact, the
underlying protocols that the CSOM used to talk to SharePoint were XML
and JSON (JavaScript Object Notation) and were fully documented so that
other systems capable of HTTP requests could make the same calls if
they wanted. This was a huge step ahead of the SharePoint Server OM
because your code could run remotely. It also hid much of the pain and
overhead of having to deal with the SOAP Web services. However, the
first version had one major drawback: it only provided API coverage to
features in SharePoint Foundation such as sites, lists, and documents,
and not to features available in the SharePoint Server standard or
enterprise versions of the software.
SharePoint 2013 has added focus on remote APIs with the CSOM and its underlying protocols as the
primary API for interacting with SharePoint moving forward. SharePoint
2013 provides access to its APIs in several forms to assist developers:
- Managed code assemblies (.NET)
- JavaScript
- REST/OData
- Windows Phone assemblies
- Silverlight assemblies
Depending on your solution or project you must
decide on the suitability and applicability of using one or more of the
preceding to accomplish your tasks. For example, if you are building a
Windows Forms application for Windows with C# you would use the Managed
CSOM. If you are building a Web Part/app part for SharePoint you can
use the JavaScript CSOM in your app’s front-end code and the Managed
CSOM for the server-side code.
If you find that an applicable precompiled
library doesn’t exist for the platform you are using then you must
consider the REST/OData endpoints. They provide Web standards–based
HTTP/HTTPS endpoints that are platform agnostic.
Underlying all of these choices is a
standards-based protocol based on REST, OData, and XML. Each of the
libraries simply abstracts the complexity of calling the underpinning
services for you and adds a layer of helper libraries to nicely package
those up.
At the heart of the new API set is _API. This is a consolidated single endpoint for all remote APIs in SharePoint 2013. _API refers to the location from which it is accessible in the SharePoint URL structure: http://yourservername/sitename/_api.
Although _API
provides the central location for API services, SharePoint 2010 also
supported (in a more limited manner) some REST services with the ListData.svcListData.svc service will be glad to hear backward compatibility has been preserved in SharePoint 2013 by leaving the ListData.svc path in place. service. Those of you who are familiar with the
_API is
fully REST and OData enabled. REST stands for Representational State
Transfer, and people commonly refer to an API as RESTful when it meets
the definition laid out as part of the founding REST principles.
The Open Data Protocol (OData) specifies a
protocol for requesting and working with data over commonly accepted
Web protocols such as HTTP, JSON, and XML. OData builds on the
principles of REST to provide a common resourcing URL structure and
parameter system to make querying and working with data simpler.
_API builds
on the foundation laid in the SharePoint 2010 CSOM by providing access
to many more areas of SharePoint, including the following:
- Lists and libraries
- User profiles
- Search
- Workflow
- Publishing
- Social feeds and sharing
- Taxonomy
- Web
- Business data
