- Article
SharePoint includes 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.
Prerequisites
This topic assumes you have a basic familiarity with REST and how to construct REST requests.
SharePoint 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 by using the OData standard, which corresponds to the desired client object model API. For example:
- CSOM
- http
var items = List.GetByTitle(listname).GetItems();The client.svc web service in SharePoint handles the HTTP request and serves the appropriate response in either Atom or JavaScript Object Notation (JSON) format. Your client application must then parse that response. The following figure shows a high-level view of the SharePoint REST architecture.
SharePoint REST service architecture
Because of the functionality and ease of use that client object models provide, they remain the primary development option for communicating with SharePoint sites by using the .NET Framework, Silverlight (now deprecated), or JavaScript (JSOM).
To use the REST capabilities that are built into SharePoint, you construct a RESTful HTTP request by using the OData standard, which corresponds to the client object model API you want to use. The client.svc web service handles the HTTP request and serves the appropriate response in either Atom or JSON format. The client application must then parse that response.
The endpoints in the SharePoint REST service correspond to the types and members in the SharePoint client object models. By using HTTP requests, you can use these REST endpoints to do typical CRUD operations against SharePoint entities, such as lists and sites.
| If you want to do this to an endpoint | Use this HTTP request | Keep in mind |
|---|---|---|
| Read a resource | GET | |
| Create or update a resource | POST |
|
| Update or insert a resource | PUT |
|
| Delete a resource | DELETE |
|
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:
https://{site_url}/_api/siteTo access a specific site, use the following construction:
https://{site_url}/_api/webIn 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 (/).
This syntax doesn't apply to the SocialFeedManager or SocialFollowingManager REST APIs. For more information, see:
- Social feed REST API reference for SharePoint
- Following people and content REST API reference for SharePoint
For more guidelines for determining SharePoint REST endpoint URIs from the signature of the corresponding client object model APIs, see Determine SharePoint REST service endpoint URIs.
The following table contains typical REST endpoint URL examples to get you started working with SharePoint data. Prepend http://server/site/_api/ to the URL fragments shown in the table to construct a fully qualified REST URL. Where necessary for POST commands, the table contains sample data you must pass in the HTTP request body to create the specified SharePoint item. Items in quotes represent variables that you must replace with your values.
| Description | URL endpoint | HTTP method | Body content |
|---|---|---|---|
| Retrieves the title of a site | 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 list (in this case, the list title) | lists/getbytitle('listname')?select=Title | GET | Not applicable |
| Creates a list | lists | POST | See sample |
| Adds an item to a list | lists/getbytitle('listname')/items | POST | See sample |
Creates a list sample data:
{ "__metadata": { "type": "SP.List" }, "AllowContentTypes": true, "BaseTemplate": 104 , "ContentTypesEnabled": true, "Description": "My list description ", "Title": "RestTest "}Adds an item to a list sample data:
{ "__metadata": { "type": "SP.Data.listname.ListItem" }, "Title": "MyItem"}In the above JSON, replace listname with the name of your SharePoint list by omitting the spaces.
Batch job support
The SharePoint Online (and on-premises SharePoint 2016 or later) REST service supports combining multiple requests into a single call to the service by using the OData $batch query option. For details and links to code samples, see Make batch requests with the REST APIs.
OData resources
- Developing Service-Oriented Applications with WCF
- Open Data Protocol
- OData Protocol URI Conventions
- Addressing Service Operations
- OData Protocol Operations
- Error Conditions
To learn more about using the SharePoint REST service, use the following resources.
| Title | Description |
|---|---|
| Complete basic operations using SharePoint REST endpoints | Perform basic create, read, update, and delete (CRUD) operations with the SharePoint REST interface. |
| Working with lists and list items with REST | Perform basic CRUD operations on lists and list items with the SharePoint REST interface. |
| Working with folders and files with REST | Perform basic CRUD operations on folders and files with the SharePoint REST interface. |
| Navigate the SharePoint data structure represented in the REST service | Start from a REST endpoint for a given SharePoint item, and navigate to and access-related items, such as parent sites or the library structure where that item resides. |
| Determine SharePoint REST service endpoint URIs | General guidelines for determining SharePoint REST endpoint URIs from the signature of the corresponding client object model APIs. |
| Use OData query operations in SharePoint REST requests | Use a wide range of OData query string operators to select, filter, and order the data you request from the SharePoint REST service. |
| Make batch requests with the REST APIs | Combine multiple requests into a single call to the REST service. |
| Synchronize SharePoint items using the REST service | Synchronize items between SharePoint and your add-ins or services by using the GetListItemChangesSinceToken resource, part of the SharePoint REST service. |
| Upload a file by using the REST API and jQuery | The code examples in this article use the REST interface and jQuery AJAX requests to add a local file to the Documents library, and then change properties of the list item that represents the uploaded file. |
| Set custom permissions on a list by using the REST interface | SharePoint sites, lists, and list items are types of SecurableObject, which inherits the permissions of its parent. To set custom permissions for an object, you need to break its inheritance so that it stops inheriting permissions from its parent, and then define new permissions by adding or removing role assignments. |
| SharePoint workflow fundamentals | Add search functionality to client and mobile applications using the Search REST service in SharePoint Server 2013 and any technology that supports REST web requests. |
| Social feed REST API reference for SharePoint | SharePoint REST endpoints for feed-related tasks. |
| Following people and content REST API reference for SharePoint | SharePoint REST endpoints for following people and content. |
| Develop SharePoint Add-ins | Find in-depth articles and resources to help you build advanced capabilities into your SharePoint Add-ins. |
