Skip to content

Commit dd464fc

Browse files
andrewconnellandrewconnell
committed
SP REST API docs cleanup
- update markdown formatting - apply changes to improve readability score - update links pointing to MSDN/TECHNET to docs.microsoft.com
1 parent b4e0bc1 commit dd464fc

6 files changed

+283
-333
lines changed

‎docs/sp-add-ins/complete-basic-operations-using-sharepoint-client-library-code.md

Lines changed: 89 additions & 99 deletions
Large diffs are not rendered by default.

‎docs/sp-add-ins/determine-sharepoint-rest-service-endpoint-uris.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ Before you can access a SharePoint resource using the REST service, you first ha
2222
# [CSOM](#tab/csom)
2323
<!-- {
2424
"blockType": "request",
25-
"name": "sharepoint_rest"
25+
"name": "sharepoint_rest"
2626
}-->
2727

2828
```csharp

‎docs/sp-add-ins/get-to-know-the-sharepoint-rest-service.md

Lines changed: 32 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,62 @@
11
---
22
title: Get to know the SharePoint REST service
33
description: Basics of using the SharePoint REST service to access and update SharePoint data, using the REST and OData web protocol standards.
4-
ms.date: 02/07/2018
4+
ms.date: 1/15/2020
55
ms.prod: sharepoint
66
localization_priority: Priority
77
---
88

99
# Get to know the SharePoint REST service
1010

11-
SharePoint introduces a Representational State Transfer (REST) service that is comparable to the existing SharePoint [client object models](https://msdn.microsoft.com/library/88e5e1b9-eab2-4f3b-a3f2-75c96b86f1f4%28Office.15%29.aspx). 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.
11+
SharePoint includes a Representational State Transfer (REST) service that is comparable to the existing SharePoint [client object models](/previous-versions/office/sharepoint-csom/jj193041(v=office.15)). 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.
1212

1313
## Prerequisites
1414

1515
This topic assumes you have a basic familiarity with REST and how to construct REST requests.
1616

17-
<a name="bk_how"> </a>
18-
1917
## How the SharePoint REST service works
2018

2119
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.
2220

2321
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:
2422

25-
*Client object model method:*
23+
# [CSOM](#tab/csom)
24+
<!-- {
25+
"blockType": "request",
26+
"name": "sharepoint_rest"
27+
}-->
2628

27-
```cs
28-
List.GetByTitle(listname)
29+
```csharp
30+
var items = List.GetByTitle(listname).GetItems();
2931
```
30-
31-
*REST endpoint:*
32-
32+
# [http](#tab/http)
3333
```http
34-
http://server/site/_api/lists/getbytitle('listname')
34+
GET https://{site_url}/_api/lists/getbytitle('{list_name}')/items
35+
Authorization: "Bearer " + accessToken
36+
Accept: "application/json;odata=verbose"
3537
```
38+
---
3639

3740
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.
3841

3942
**SharePoint REST service architecture**
4043

4144
![SharePoint REST service architecture](../images/SPF15Con_REST_RESTStructure.png)
4245

43-
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 .NET Framework managed code, Silverlight, or JavaScript.
44-
45-
<a name="bk_usingHTTP"> </a>
46+
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).
4647

4748
### Use HTTP commands with the SharePoint REST service
4849

4950
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.
5051

51-
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 perform typical CRUD operations against SharePoint entities, such as lists and sites.
52+
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.
5253

5354
| **If you want to do this to an endpoint** | **Use this HTTP request** | **Keep in mind** |
5455
| :---------------------------------------- | :------------------------ | :--------------------------------------------------------- |
5556
| Read a resource | **GET** | |
56-
| Create or update a resource | **POST** | <ul><li>Use **POST** to create entities such as lists and sites.</li><li>The SharePoint REST service supports sending **POST** commands that include object definitions to endpoints that represent collections.</li><li>For **POST** operations, any properties that are not required are set to their default values.</li><li>If you attempt to set a read-only property as part of a **POST** operation, the service returns an exception.</li></ul> |
57-
| Update or insert a resource | **PUT** | <ul><li>Use **PUT** and **MERGE** operations to update existing SharePoint objects.</li><li>Any service endpoint that represents an object property **set** operation supports both **PUT** requests and **MERGE** requests.</li><li>For **MERGE** requests, setting properties is optional; any properties that you do not explicitly set retain their current property.</li><li>For **PUT** requests, if you do not specify all required properties in object updates, the REST service returns an exception.</li><li>In addition, any optional properties you do not explicitly set are set to their default properties.</li></ul> |
58-
| Delete a resource |**DELETE**| <ul><li>Use the HTTP **DELETE** command against the specific endpoint URL to delete the SharePoint object represented by that endpoint.</li><li>In the case of recyclable objects, such as lists, files, and list items, this results in a **Recycle** operation. </li></ul>|
59-
60-
<a name="bk_constructURLs"> </a>
57+
| Create or update a resource | **POST** | <ul><li>Use **POST** to create entities such as lists and sites.</li><li>The SharePoint REST service supports sending **POST** commands that include object definitions to endpoints that represent collections.</li><li>For **POST** operations, any properties that aren't required are set to their default values.</li><li>If you attempt to set a read-only property as part of a **POST** operation, the service returns an exception.</li></ul> |
58+
| Update or insert a resource | **PUT** | <ul><li>Use **PUT** and **MERGE** operations to update existing SharePoint objects.</li><li>Any service endpoint that represents an object property **set** operation supports both **PUT** requests and **MERGE** requests.</li><li>For **MERGE** requests, setting properties is optional; any properties that you don't explicitly set keep their current property.</li><li>For **PUT** requests, if you don't specify all required properties in object updates, the REST service returns an exception.</li><li>In addition, any optional properties you don't explicitly specify are set to their default properties.</li></ul> |
59+
| Delete a resource |**DELETE**| <ul><li>Use the HTTP **DELETE** command against the specific endpoint URL to delete the SharePoint object represented by that endpoint.</li><li>There are recyclable objects, such as lists, files, and list items, this results in a **Recycle** operation. </li></ul>|
6160

6261
### Construct REST URLs to access SharePoint resources
6362

@@ -66,13 +65,13 @@ Whenever possible, the URI for these REST endpoints closely mimics the API signa
6665
To access a specific site collection, use the following construction:
6766

6867
```http
69-
http://server/site/_api/site
68+
https://{site_url}/_api/site
7069
```
7170

7271
To access a specific site, use the following construction:
7372

7473
```http
75-
http://server/site/_api/web
74+
https://{site_url}/_api/web
7675
```
7776

7877
In each case, *server* represents the name of the server, and *site* represents the name of, or path to, the specific site.
@@ -86,8 +85,6 @@ This syntax doesn't apply to the SocialFeedManager or SocialFollowingManager RES
8685

8786
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](determine-sharepoint-rest-service-endpoint-uris.md).
8887

89-
<a name="bk_URLexamples"> </a>
90-
9188
## SharePoint REST endpoint examples
9289

9390
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.
@@ -106,38 +103,34 @@ The following table contains typical REST endpoint URL examples to get you start
106103

107104
```json
108105
{
109-
'__metadata': {
110-
'type': 'SP.List'
106+
"__metadata": {
107+
"type": "SP.List"
111108
},
112-
'AllowContentTypes': true,
113-
'BaseTemplate': 104 ,
114-
'ContentTypesEnabled': true,
115-
'Description': 'My list description ',
116-
'Title': 'RestTest '
109+
"AllowContentTypes": true,
110+
"BaseTemplate": 104 ,
111+
"ContentTypesEnabled": true,
112+
"Description": "My list description ",
113+
"Title": "RestTest "
117114
}
118115
```
119116

120117
**Adds an item to a list** sample data:
121118

122119
```json
123120
{
124-
'__metadata': {
125-
'type': 'SP.Data.listname.ListItem'
121+
"__metadata": {
122+
"type": "SP.Data.listname.ListItem"
126123
},
127-
'Title': 'MyItem'
124+
"Title": "MyItem"
128125
}
129126
```
130127

131128
In the above JSON, replace listname with the name of your SharePoint list by omitting the spaces.
132129

133-
<a name="batch"> </a>
134-
135130
## Batch job support
136131

137132
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](make-batch-requests-with-the-rest-apis.md).
138133

139-
<a name="SP15startREST_bk_addlresources"> </a>
140-
141134
## OData resources
142135

143136
- [Developing Service-Oriented Applications with WCF](https://docs.microsoft.com/dotnet/framework/wcf/index)
@@ -147,8 +140,6 @@ The SharePoint Online (and on-premises SharePoint 2016 or later) REST service su
147140
- [OData Protocol Operations](http://www.odata.org/documentation/odata-version-2-0/operations/)
148141
- [Error Conditions](http://www.odata.org/documentation/odata-version-2-0/operations#ErrorConditions)
149142

150-
<a name="bk_learnmore"> </a>
151-
152143
## SharePoint REST service topics
153144

154145
To learn more about using the SharePoint REST service, use the following resources.
@@ -158,7 +149,7 @@ To learn more about using the SharePoint REST service, use the following resourc
158149
| [Complete basic operations using SharePoint REST endpoints](complete-basic-operations-using-sharepoint-rest-endpoints.md) | Perform basic create, read, update, and delete (CRUD) operations with the SharePoint REST interface. |
159150
| [Working with lists and list items with REST](working-with-lists-and-list-items-with-rest.md) | Perform basic CRUD operations on lists and list items with the SharePoint REST interface. |
160151
| [Working with folders and files with REST](working-with-folders-and-files-with-rest.md) | Perform basic CRUD operations on folders and files with the SharePoint REST interface. |
161-
| [Navigate the SharePoint data structure represented in the REST service](navigate-the-sharepoint-data-structure-represented-in-the-rest-service.md) | 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. |
152+
| [Navigate the SharePoint data structure represented in the REST service](navigate-the-sharepoint-data-structure-represented-in-the-rest-service.md) | 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. |
162153
| [Determine SharePoint REST service endpoint URIs](determine-sharepoint-rest-service-endpoint-uris.md) | General guidelines for determining SharePoint REST endpoint URIs from the signature of the corresponding client object model APIs. |
163154
| [Use OData query operations in SharePoint REST requests](use-odata-query-operations-in-sharepoint-rest-requests.md) | Use a wide range of OData query string operators to select, filter, and order the data you request from the SharePoint REST service. |
164155
| [Make batch requests with the REST APIs](make-batch-requests-with-the-rest-apis.md) | Combine multiple requests into a single call to the REST service. |

0 commit comments

Comments
 (0)