SharePoint exposes a REST interface that allows us to\nperform basic create, read, update, and delete (CRUD) operations on its entities.\nThese operations are performed by constructing a RESTful HTTP request, using\nthe OData standard, that corresponds to the client object model API you want to\nuse.<\/p>\n\n\n\n
Each SharePoint entity is exposed at an endpoint on the\nSharePoint site that you are targeting, and its metadata is represented in\neither XML or JSON format. This means, to perform any operation using a REST\nendpoint, you must know both the URL of the endpoint and the OData\nrepresentation of the SharePoint entity that is exposed at that endpoint.<\/p>\n\n\n\n
Endpoints that represents read operations are access using HTTP\nGET<\/strong> request. Endpoints that represents create operations map to HTTP POST<\/strong>.\nWhen you’re updating entities, you use PUT<\/strong> or MERGE<\/strong> HTTP request.\nUse the DELETE<\/strong> method to delete the entity. <\/p>\n\n\n\n I mentioned we can use PUT <\/strong>or MERGE <\/strong>request when updating entities, so which one is preferable? The answer is none, it depends on what you want to achieve. The MERGE<\/strong> method updates only the properties of the entity that you specify, while the PUT<\/strong> method replaces the existing entity with a new one that you supply.<\/p>\n\n\n\n All request to SharePoint endpoints will be authenticated. The method you will use to authenticate will vary based on how you are accessing the endpoints. <\/p>\n\n\n\n You need to get an access token when you use OAuth authentication. You cannot obtain an access token from code that is running on a browser client. You must obtain the access token from code that is running on a server. For more information about how you can obtain an access token, see\u00a0Context Token OAuth flow for SharePoint Add-ins<\/a>\u00a0and\u00a0Authorization Code OAuth flow for SharePoint Add-ins<\/a>.<\/p>\n\n\n\n To read information from a REST endpoint, you must know both the URL of the endpoint and the OData representation of the SharePoint entity that is exposed at that endpoint. You also need a valid OAuth access token. <\/p>\n\n\n\n You do not need the access token if you make this call from inside an add-in web, as you would in a SharePoint-hosted add-in. <\/p>\n\n\n\n This request would look a little different if you are writing your add-in in JavaScript while using the SharePoint cross-domain library. In this case, you don’t need to provide an access token. <\/p>\n\n\n\n You can create and update SharePoint entities by constructing RESTful HTTP requests to the appropriate endpoints, just as you do when you’re reading data. If you aren’t using OAuth to authorize your requests, these operations require the server’s request form digest value as the value of the\u00a0 In Provider-hosted add-ins that use OAuth, first retrieve the form digest value by making a POST request with an empty body to Another option is using the JavaScript cross-domain library. For provider hosted page, the HTTP requests will be from a remote webpage. For security, browsers do not allow JavaScript that is hosted on one domain to access resources on another domain. The JavaScript cross-domain library The table shows properties that are commonly used in HTTP requests for the SharePoint REST service.<\/p>\n\n\n\n References<\/strong><\/p>\n https:\/\/docs.microsoft.com\/en-us\/sharepoint\/dev\/sp-add-ins\/sharepoint-net-server-csom-jsom-and-rest-api-index<\/a><\/p>\nRequest Authentication<\/i><\/a><\/h2>\n\n\n\n
Reading data with the SharePoint REST interface <\/i><\/a><\/h3>\n\n\n\n
HttpWebRequest endpointRequest =\n (HttpWebRequest)HttpWebRequest.Create(\n \"http:\/\/<site url>\/_api\/web\/lists\");\nendpointRequest.Method = \"GET\";\nendpointRequest.Accept = \"application\/json;odata=verbose\";\nendpointRequest.Headers.Add(\"Authorization\",\n \"Bearer \" + accessToken);\nHttpWebResponse endpointResponse =\n (HttpWebResponse)endpointRequest.GetResponse();<\/code><\/pre>\n\n\n\nvar executor = new SP.RequestExecutor(appweburl);\nexecutor.executeAsync(\n {\n url: appweburl +\n \"\/_api\/SP.AppContextSite(@target)\/web\/lists?@target='\" +\n hostweburl + \"'\",\n method: \"GET\",\n success: successHandler,\n error: errorHandler\n }\n);<\/code><\/pre>\n\n\n\nWriting data by using the REST interface<\/i><\/a><\/h3>\n\n\n\n
X-RequestDigest<\/code> \u00a0header.\u00a0 <\/p>\n\n\n\njQuery.ajax({\n url: \"http:\/\/<site url>\/_api\/web\/lists\",\n type: \"POST\",\n data: JSON.stringify({ '__metadata': { 'type': 'SP.List' }, 'AllowContentTypes': true,\n 'BaseTemplate': 100, 'ContentTypesEnabled': true, 'Description': 'My list description', 'Title': 'Test' }\n),\n headers: { \n \"accept\": \"application\/json;odata=verbose\",\n \"content-type\": \"application\/json;odata=verbose\",\n \"content-length\": <length of post body>,\n \"X-RequestDigest\": $(\"#__REQUESTDIGEST\").val()\n },\n success: doSuccess,\n error: doError\n});<\/code><\/pre>\n\n\n\nhttp:\/\/<site url>\/_api\/contextinfo<\/code> and extracting the value of the d:FormDigestValue<\/code> node in the XML that the contextinfo endpoint returns.<\/p>\n\n\n\nSP.RequestExecutor<\/code> handles getting and sending the form digest value for you. (It also handles the content-length value.)<\/p>\n\n\n\nvar executor = new SP.RequestExecutor(appweburl);\nexecutor.executeAsync(\n {\n url:\"http:\/\/<site url>\/_api\/web\/lists\",\n method: \"GET\",\n success: successHandler,\n error: errorHandler\n }\n);<\/code><\/pre>\n\n\n\nProperties used in REST requests<\/i><\/a><\/h2>\n\n\n\n
Properties<\/strong> <\/td> When required<\/strong> <\/td> \n Description<\/strong>\n <\/td><\/tr><\/thead> url<\/strong> <\/td> \n All requests\n <\/td> The URL of the REST resource endpoint. Example: http:\/\/<site url>\/_api\/web\/lists <\/td><\/tr> method<\/strong> (or type<\/strong>) <\/td> \n All requests\n <\/td> The HTTP request method: GET<\/strong> for read operations and POST<\/strong> for write operations. POST<\/strong> requests can perform update or delete operations by specifying a DELETE<\/strong>, MERGE<\/strong>, or PUT<\/strong> verb in the X-HTTP-Method<\/strong> header. <\/td><\/tr> body<\/strong> (or data<\/strong>) <\/td> POST<\/strong> requests that send data in the request body <\/td> The body of the POST request. Sends data (such as complex types) that can’t be sent in the endpoint URI. Used with the content-length<\/strong> header. <\/td><\/tr> Authentication<\/strong> header <\/td> Remote add-ins that are using OAuth to authenticate users; does not apply when using JavaScript or the cross domain library <\/td> Sends the OAuth access token (obtained from a Microsoft Access Control Service (ACS) secure token server) that’s used to authenticate the user for the request. Example: “Authorization”: “Bearer ” + accessToken, where accessToken represents the variable that stores the token. Tokens must be retrieved by using server-side code. <\/td><\/tr> \n X-RequestDigest<\/strong> header\n <\/td> POST<\/strong> requests (except SP.RequestExecutor requests) <\/td> Remote add-ins that use OAuth can get the form digest value from the http:\/\/<site url>\/_api\/contextinfo endpoint. SharePoint-hosted add-ins can get the value from the #__REQUESTDIGEST<\/strong> page control if it’s available on the SharePoint page. <\/td><\/tr> accept<\/strong> header <\/td> Requests that return SharePoint metadata <\/td> Specifies the format for response data from the server. The default format is application\/atom+xml. Example: “accept”:”application\/json;odata=verbose” <\/td><\/tr> content-type<\/strong> header <\/td> POST<\/strong> requests that send data in the request body <\/td> Specifies the format of the data that the client is sending to the server. The default format is application\/atom+xml. Example: “content-type”:”application\/json;odata=verbose” <\/td><\/tr> content-length<\/strong> header <\/td> POST<\/strong> requests that send data in the request body (except SP.RequestExecutor requests) <\/td> Specifies the length of the content. Example: “content-length”:requestBody.length <\/td><\/tr> IF-MATCH<\/strong> header <\/td> POST<\/strong> requests for DELETE<\/strong>, MERGE<\/strong>, or PUT<\/strong> operations, primarily for changing lists and libraries <\/td> Provides a way to verify that the object being changed has not been changed since it was last retrieved. Or, lets you specify to overwrite any changes, as shown in the following example: “IF-MATCH”:”*” <\/td><\/tr> X-HTTP-Method<\/strong> header <\/td> POST<\/strong> requests for DELETE<\/strong>, MERGE<\/strong>, or PUT<\/strong> operations <\/td> Used to specify that the request performs an update or delete operation. Example: “X-HTTP-Method”:”PUT” <\/td><\/tr> binaryStringRequestBody<\/strong> <\/td> SP.RequestExecutor POST<\/strong> requests that send binary data in the body <\/td> Specifies whether the request body is a binary string. Boolean<\/strong>. <\/td><\/tr> binaryStringResponseBody<\/strong> <\/td> SP.RequestExecutor requests that return binary data <\/td> Specifies whether the response is a binary string. Boolean<\/strong>. <\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n