REpresentational State Transfer
(REST) is a prevalent pattern for designing easily consumed data APIs
over the Internet. You might hear an API described as RESTful if it is
designed to be used over HTTP protocols and is in line with the
principles of REST. These principles are as follows:
- Client-Server: The client is unaware of how the server stores or manages the data and doesn’t need to know in order to use the API.
- Stateless: The server does not store any context or state about the calling client.
- Cacheable: The results of the calls to the API define themselves as being cacheable, or not.
- Layered: The client does not mind whether the call to the API is transmitted via common Internet technology such as load balancers.
- Uniform Interface: This provides a
simple and known way to access data through standard URI addressing and
self-describing so that a client can discover how to access data.
Many services offer REST-based APIs to ease
access to their systems in a commonly understood manner. SharePoint
2013 builds on this foundation to offer access in a “RESTful” way to
allow remote systems to interact with it in a platform agnostic and
open way. For developers this means that using other helper libraries
and frameworks for working with REST is a viable method, and the time
to become proficient in a proprietary API is decreased.
OData or Open Data Protocol is a protocol
definition for querying, finding, and updating data over HTTP. It
offers defined methods for specifying common query operations and
defines the format in which data is returned. SharePoint 2013 uses WCF
Data Services v5.0 which implements the OData v3 specification. For
more information on OData you can visit: http://www.odata.org.
Combining a RESTful Web API with OData gives a
powerful combination of simple and easy-to-use APIs that have a
well-defined interface and interaction model. In practical terms,
having access to a RESTful OData-based API means the following for
SharePoint developers:
- Standard URIs for addressing data
- Simple use of GET, POST, PUT/MERGE, and DELETE HTTP methods
- JSON or XML (ATOM) responses
- Simple query/filter semantics
The following sections describe each of the
preceding points with simple-to-follow examples of how they are
addressed in SharePoint 2013’s implementation of its REST/OData Web API
endpoints.
Getting Started with REST and OData
You can find SharePoint’s REST/OData APIs in the _API URL space under each SharePoint site. For example:
https://servername/sitename/_api/
_api is the root URI for all REST/OData calls. SharePoint also supports calls to the _vti_bin/client.svc/ URI to maintain backward compatibility with the previously available but more limited REST API in SharePoint 2010.
To query for data, issue a GET request. To update data you use either a PUT or MERGE
request passing the data you want to update. But first you must specify
which namespace it belongs in, such as Web, Site, or Search. Other
groups include:
- _api/web
- _api/site
- _api/search
- _api/publishing
After you specify a namespace you must address an object, method, indexer, or property on it. Figure 1 depicts the URI address system.
To retrieve the list of lists on a SharePoint site simply issue a GET request to the following:
https://servername/sitename/_api/web/lists
To retrieve the details about a list simply make a GET request to that list’s URI indicated in the previous response’s id property. For example:
https://servername/sitename/_api/Web/Lists(guid'f57d3ddc-4522-4145-a0fe-72abbd6ea8fc')
This example uses the Lists method with a parameter to specify the ID of the list. You could also use the list’s entity name; for example:
https://servername/sitename/_api/Web/Lists/MoviesList
Additionally, you can address a list by name using the getbytitle function as follows. This addresses the list with its name versus its entity name:
https://servername/sitename/_api/Web/Lists/getbytitle('movies')/items
To access the items within a list add /items to the URI:
https://servername/sitename/_api/Web/Lists/MoviesList/Items
By default you will receive an ATOM feed
XML response containing the lists in your site. If you want to receive
a JSON payload instead, set the HTTP Accept header to application/json;odata=verbose.
This signals that you want JSON instead of the default ATOM payload.
JSON is typically lighter weight and better suited to mobile scenarios
where speed is important.
