Sharepoint online Rest API

How the SharePoint REST service works

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:

HTTP :

GET https://{site_url}/_api/lists/getbytitle('{list_name}')/items
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

Use HTTP commands with the SharePoint REST service

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 Use this Keep in mind

to do this to HTTP
an endpoint request
Read a GET
resource
Create or POST  Use POST to create entities such as lists
update a and sites.
resource  The SharePoint REST service supports
sending POST commands that include
object definitions to endpoints that
represent collections.
 For POST operations, any properties
that aren't 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.
Update or PUT and  Use PUT and MERGE operations to
insert a MERGE update existing SharePoint objects.
resource  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 don't
explicitly set keep their current property.
 For PUT requests, if you don't specify
all required properties in object updates,
the REST service returns an exception.
 In addition, any optional properties you
don't explicitly specify are set to their
default properties.
Delete a DELETE  Use the HTTP DELETE command
resource against the specific endpoint URL to
delete the SharePoint object represented
by that endpoint.
 There are recyclable objects, such as
lists, files, and list items, this results in a
Recycle operation.

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 :

https://{site_url}/_api/site

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

HTTP :

https://{site_url}/_api/web

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

SharePoint REST endpoints :

Descripti URL endpoint HTTP Body

on metho content
d
Retrieves web/title GET Not
the title of applicab
a site le
Retrieves lists GET Not
all lists on applicab
a site le
Retrieves lists/getbytitle('listname') GET Not
a single applicab
list's le
metadata
Retrieves lists/getbytitle('listname')/items GET Not
items applicab
within a le
list
Retrieves lists/getbytitle('listname')? GET Not
select=Title
a specific applicab
property le
of a list
(in this
case, the
list title)
Creates a lists POST See
list sample
Adds an lists/getbytitle('listname')/items POST See
item to a sample
list

Operati SharePoint Rest API endpoint

on
Retrieve https:///{site url}/_api/site
SharePo
int Site
Collecti
on
Retrieve https:///{site url}/_api/web
a
particula
r
SharePo
int Site
or Web
Retrieve https://{site url}/_api/web/title
SharePo
int Site
Title
Retrieve https:///{site url}/_api/web/lists
all
SharePo
int Lists
Retrieve https:///{site url}/_api/web/lists/getbytitle(‘listname’)/items
all the
Items
from a
SharePo
int List
Retrieve https:///{site url}/_api/web/lists/getbytitle(‘listname’)?select=Title
SharePo
int List
Title
Retrieve https:///{site url}/_api/web/lists/getbytitle(‘listname’)/Fields
all the
columns
of a
SharePo
int List
Retrieve https:///{site url}/_api/Web/Lists(List GUID)
a
SharePo
int List
by using
List
GUID
Retrieve https:///{site
a url}/_api/web/lists/GetByTitle(‘listname’)/GetItemById(2)
SharePo
int List
Item by
Item Id
Retrieve https:///{site url}/_api/Web/currentUser
SharePo
int
Current
User
Informat
ion
Retrieve https:///{site url}/_api/web/lists/getbytitle(‘listname’)/Items?
selected select=ID,Title,FirstName,LastName
Fields of
a
SharePo
int List
Items
Retrieve https:///{site url}/_api/Web/siteusers
all
SharePo
int Site
Users
Retrieve https:///{site url}/_api/Web/sitegroups
all
Groups
from a
SharePo
int Site
Retrieve https:///{site url}/_api/Web/sitegroups/GetById(GroupId)
a
particula
r
SharePo
int
Group
by
Group
Id
Retrieve https:///{site url}/_api/Web/sitegroups(Id)/users
all the
Users
from a
SharePo
int
Group
API
AttachmentCollection
SPAttachmentCollection
BasePermissions
SPBasePermissions
CalendarType SPCalendarType
ChangeCollection
SPChangeCollection
ChangeSite SPChangeSite
ClientContext
ContentType SPContentType
ContentTypeCollection
SPContentTypeCollection
SPContext
EventReceiverDefinition
SPEventReceiverDefinition
EventReceiverDefinitionCollectio
n ction object
SPEventReceiverDefinitionCollec
tion
EventReceiverDefinitionCreation
Information
SPEventReceiverDefinitionCreati
onInformation
EventReceiverType
SPEventReceiverType
Feature SPFeature
FeatureCollection
SPFeatureCollection
FeatureDefinitionScope
SPFeatureDefinitionScope
Field SPField
FieldCalculated
SPFieldCalculated
FieldChoice SPFieldChoice
FieldCollection
SPFieldCollection
FieldComputed
SPFieldComputed
FieldCurrency SPFieldCurrency
FieldLink SPFieldLink
Form SPForm
Navigation SPNavigation
SP.Object/Enumeration (sp.js)
SP.AttachmentCollection
SP.BasePermissions object
SP.CalendarType enumeration
SP.ChangeCollection object
SP.ChangeSite enumeration
SP.ClientContext object
SP.ContentType object
SP.ContentTypeCollection object
SP.RequestContext object
SP.EventReceiverDefinition
object
SP.EventReceiverDefinitionColle
SP.EventReceiverDefinitionCreat
ionInformation object
SP.EventReceiverType
enumeration
SP.Feature object
SP.FeatureCollection object
SP.FeatureDefinitionScope
enumeration
SP.Field object
SP.FieldCalculated object
SP.FieldChoice object
SP.FieldCollection object
SP.FieldComputed object
SP.FieldCurrency object
SP.FieldLink object
SP.Form object
SP.Navigation object
REST Endpoint
…/_api/web/lists('<list
id>')/items(<item
id>)/attachmentfiles
N/A
N/A
…/_api/web/
getchanges(changequery)
N/A
…/_api/contextinfo
…/_api/web/
contenttypes('<content type
id>')
…/_api/web/contenttypes
N/A
…/_api/web/eventreceivers
…/_api/web/
eventreceivers(eventreceiveri
d)
N/A
N/A
…/_api/web/
features(featureid)
…/_api/web/features
N/A
…/_api/web/fields('<field id>')
…/_api/web/fields('<field id>')
…/_api/web/fields('<field id>')
…/_api/web/fields
…/_api/web/fields('<field id>')
…/_api/web/fields('<field id>')
…/_api/web/
contenttypes('<content type
id>')/fieldlinks('<field link
id>')
…/_api/web/lists(guid'<list
id>')/forms('<form id>')
…/_api/web/navigation
RecycleBinItem
SPRecycleBinItem
RecycleBinItemCollection
SPRecycleBinItemCollection
RegionalSettings SPRegionalSettings SP.RegionalSettings object
Properties used in REST requests
Table 2 shows properties that are commonly used in HTTP requests for the SharePoint REST service.
Table 2. When to use REST request properties in HTTP requests
Properties
url
method (or type)
body (or data)
Authentication header
X-RequestDigest header
accept header
content-type header
content-length header
IF-MATCH header
SP.RecycleBinItem object …/_api/web/RecycleBin(recyclebinitemid)
SP.RecycleBinItemCollection object …/_api/web/RecycleBin
…/_api/web/RegionalSettings
When required Description
All requests The URL of the REST resource endpoint.
Example: http://<site url>/_api/web/lists
All requests The HTTP request method: GET for read
operations and POST for write operations. POST
requests can perform update or delete operations by
specifying a DELETE, MERGE, or PUT verb in
the X-HTTP-Method header.
POST requests that The body of the POST request. Sends data (such as
send data in the complex types) that can't be sent in the endpoint
request body URI. Used with the content-length header.
Remote add-ins that Sends the OAuth access token (obtained from a
are using OAuth to Microsoft Access Control Service (ACS) secure
authenticate users; token server) that's used to authenticate the user for
does not apply when the request. Example: "Authorization":
using JavaScript or "Bearer " + accessToken, where accessToken
the cross domain represents the variable that stores the token. Tokens
library must be retrieved by using server-side code.
POST requests Remote add-ins that use OAuth can get the form
(except digest value from the http://<site
SP.RequestExecutor url>/_api/contextinfo endpoint. SharePoint-
requests) hosted add-ins can get the value from the
#__REQUESTDIGEST page control if it's
available on the SharePoint page. See Writing data
by using the REST interface.
Requests that return Specifies the format for response data from the
SharePoint metadata server. The default format is
application/atom+xml. Example:
"accept":"application/json;odata=verbose"
POST requests that Specifies the format of the data that the client is
send data in the sending to the server. The default format is
request body application/atom+xml. Example: "content-
type":"application/json;odata=verbose"
POST requests that Specifies the length of the content. Example:
send data in the "content-length":requestBody.length
request body (except
SP.RequestExecutor
requests)
POST requests for Provides a way to verify that the object being
 DELETE, changed has not been changed since it was last
MERGE, or PUT retrieved. Or, lets you specify to overwrite any
operations, primarily changes, as shown in the following example: "IF-
for changing lists MATCH":"*"
and libraries
X-HTTP-Method header POST requests for Used to specify that the request performs an update
DELETE, or delete operation. Example: "X-HTTP-
MERGE, or PUT Method":"PUT"
operations
binaryStringRequestBody SP.RequestExecutor Specifies whether the request body is a binary
POST requests that string. Boolean.
send binary data in
the body
binaryStringResponseBod SP.RequestExecutor Specifies whether the response is a binary string.
y requests that return Boolean.
binary data

Working with lists by using REST

HTTP

POST https://{site_url}/_api/web/lists
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}
X-RequestDigest: "{form_digest_value}"

{
"__metadata": {
"type": "SP.List"
},
"AllowContentTypes": true,
"BaseTemplate": 100,
"ContentTypesEnabled": true,
"Description": "My list description",
"Title": "Test"
}

The following example shows how to update a list by using the MERGE method.

HTTP

POST https://{site_url}/_api/web/lists(guid'{list_guid}')
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}
If-Match: "{etag or *}"
X-HTTP-Method: "MERGE"
X-RequestDigest: "{form_digest_value}"

{
"__metadata": {
"type": "SP.List"
},
"Title": "New title"
}
The following example shows how to create a custom field for a list

HTTP
POST https://{site_url}/_api/web/lists(guid'{list_guid}')/Fields
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}
X-RequestDigest: "{form_digest_value}"

{
"__metadata": {
"type": "SP.Field"
},
"Title": "field title",
"FieldTypeKind": FieldType value,
"Required": "true/false",
"EnforceUniqueValues": "true/false",
"StaticName": "field name"
}

The following example shows how to delete a list.

HTTP
POST https://{site_url}/_api/web/lists(guid'{list_guid}')
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
If-Match: "{etag or *}"
X-HTTP-Method: "DELETE"
X-RequestDigest: "{form_digest_value}"

Lookup column changes

When referring to a lookup column inside a list using REST API, use the display name of the lookup column
instead of the internal name.

HTTP
GET https://{site_url}/_api/web/lists/getbytitle('ListName')/Items?&$filter=LookupColumnId
eq 1
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

Working with list items by using REST

Retrieve all list items

The following example shows how to retrieve all of a list's items :

HTTP
GET https://{site_url}/_api/web/lists/GetByTitle('Test')/items
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

Retrieve specific list item

The following example shows how to retrieve a specific list item.

HTTP
GET https://{site_url}/_api/web/lists/GetByTitle('Test')/items({item_id})
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

The following XML shows an example of the list item properties that are returned when you request the XML
content type.

XML
<content type="application/xml">
<m:properties>
<d:FileSystemObjectType m:type="Edm.Int32">0</d:FileSystemObjectType>
<d:Id m:type="Edm.Int32">1</d:Id>
<d:ID m:type="Edm.Int32">1</d:ID>
<d:ContentTypeId>0x010049564F321A0F0543BA8C6303316C8C0F</d:ContentTypeId>
<d:Title>an item</d:Title>
<d:Modified m:type="Edm.DateTime">2012-07-24T22:47:26Z</d:Modified>
<d:Created m:type="Edm.DateTime">2012-07-24T22:47:26Z</d:Created>
<d:AuthorId m:type="Edm.Int32">11</d:AuthorId>
<d:EditorId m:type="Edm.Int32">11</d:EditorId>
<d:OData__UIVersionString>1.0</d:OData__UIVersionString>
<d:Attachments m:type="Edm.Boolean">false</d:Attachments>
<d:GUID m:type="Edm.Guid">eb6850c5-9a30-4636-b282-234eda8b1057</d:GUID>
</m:properties>
</content>