How the SharePoint 2013 REST service works

In computing, representational state transfer (REST) is the software architectural style of the World Wide Web.RESTful systems typically, but not always, communicate over Hypertext Transfer Protocol (HTTP) with the same HTTP verbs (GET, POST, PUT, DELETE, etc.) which web browsers use to retrieve web pages and to send data to remote servers. REST interfaces with external systems using resources identified by Uniform Resource Identifier (URI), for example /people/tom, which can be operated upon using standard verbs, such as DELETE /people/tom.

SharePoint 2013 introduces a Representational State Transfer (REST) service that is comparable to the existing SharePoint client object models. Now, developers can interact remotely with SharePoint data by using any technology that supports REST web requests. This means that developers can perform Create, Read, Update, and Delete (CRUD) operations from their SharePoint Add-ins, solutions, and client applications, using REST web technologies and standard Open Data Protocol (OData) syntax.

SharePoint 2013 adds the ability for you to remotely interact with SharePoint sites by using REST. Now, you can interact directly with SharePoint objects by using any technology that supports standard REST capabilities.
To access SharePoint resources using REST, construct a RESTful HTTP request, using the Open Data Protocol (OData) standard, which corresponds to the desired client object model API. For example:

Client object model method:

List.GetByTitle(listname)

REST endpoint:

http://server/site/_api/lists/getbytitle('listname')

The client.svc web service in SharePoint handles the HTTP request, and serves the appropriate response in either Atom or JSON (JavaScript Object Notation) format. Your client application must then parse that response. The figure below shows a high-level view of the SharePoint REST architecture.

SharePoint REST service architecture

Construct REST URLs to access SharePoint resources

Whenever possible, the URI for these REST endpoints closely mimics the API signature of the resource in the SharePoint client object model. The main entry points for the REST service represent the site collection and site of the specified context.

To access a specific site collection, use the following construction:

http://server/site/_api/site

To access a specific site, use the following construction:

http://server/site/_api/web

In each case, server represents the name of the server, and site represents the name of, or path to, the specific site.

From this starting point, you can then construct more specific REST URIs by ''walking" the object model, using the names of the APIs from the client object model separated by a forward slash (/).

SharePoint REST endpoint examples

Description	URL endpoint	HTTP method	Body content
Retrieves the title of a list	web/title	GET	Not applicable
Retrieves all lists on a site	lists	GET	Not applicable
Retrieves a single 'list's metadata	lists/getbytitle('listname')	GET	Not applicable
Retrieves items within a list	lists/getbytitle('listname')/items	GET	Not applicable
Retrieves a specific property of a document. (In this case, the document title.)	lists/getbytitle('listname')?select=Title	GET	Not applicable
Creates a list	lists	POST	{ '_metadata':{'type':SP.List}, 'AllowContentTypes': true, 'BaseTemplate': 104, 'ContentTypesEnabled': true, 'Description': 'My list description', 'Title': 'RestTest' }
Adds an item to a list	lists/getbytitle('listname')/items	POST	{ '_metadata':{'type':SP.listnameListItem}, 'Title': 'MyItem' }