Get started with the SharePoint 2013 REST service

To use the REST capabilities that are built into SharePoint 2013, you construct a RESTful HTTP request, 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 JavaScript Object Notation (JSON) format. 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. By using HTTP requests, you can use these REST endpoints to perform typical CRUD operations against SharePoint artifacts, such as lists and sites.

In general:

• Endpoints that represent read operations map to HTTP GET commands.

• Endpoints that represent update operations map to HTTP POST commands.

• Endpoints that represent update or insert operations map to HTTP PUT commands.

In choosing an HTTP request to use, you should also consider the following:

• Use POST to create artifacts such as lists and sites. The SharePoint 2013 REST service supports sending POST commands that include object definitions to endpoints that represent collections.

• For POST operations, any properties that are not required are set to their default values. If you attempt to set a read-only property as part of a POST operation, the service returns an exception.

• Use PUT, PATCH, and MERGE operations to update existing SharePoint objects. Any service endpoint that represents an object property set operation supports both PUT requests and MERGE requests. For MERGE requests, setting properties is optional; any properties that you do not explicitly set retain their current property. For PUT commands, however, any properties you do not explicitly set are set to their default properties. In addition, if you do not specify all settable properties in object updates when using HTTP PUT commands, the REST service returns an exception.

• Use the HTTP DELETE command against the specific endpoint URL to delete the SharePoint object represented by that endpoint. In the case of recyclable objects, such as lists, files, and list items, this results in a Recycle operation.

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 (/).

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 italics represent variables that you must replace with your values.

{
  '_metadata':{'type':SP.List},
  'AllowContentTypes': true,
  'BaseTemplate': 104,
  'ContentTypesEnabled': true,
  'Description': 'My list description',
  'Title': 'RestTest'
}

{
  '_metadata':{'type':SP. listnameListItem},
  'Title': 'MyItem'
}

For an overview of the SharePoint 2013 REST service, including additional guidelines and restrictions about constructing REST endpoint URLs, see Programming using the SharePoint 2013 REST service. For detailed instructions and additional examples on using the REST service to perform common CRUD operations against SharePoint artifacts such as sites, lists, and items, see Using the SharePoint 2013 REST service.

• Programming using the SharePoint 2013 REST service

• Using the SharePoint 2013 REST service