Overview of REST APIs in Office 365 and SharePoint

Hesam Seyed Mousavi, October 31, 2017


The REST APIs are very straightforward and easy to use and allow for a platform-agnostic development approach. Each query that is submitted is done via a unique URL, and the returned results can be cached by proxy servers. The REST APIs are easier to utilize than a SOAP-based web service and provide for higher productivity when JavaScript and jQuery are used.

Source: dotnetsharper


Hesam_Seyed_Mousavi_REST API in Office 365 and SharePoint

You can access resources utilizing REST capabilities in SharePoint by constructing a RESTful HTTP request, using OData, which corresponds to the desired client object model API.

The client.svc service handles the HTTP request and serves the appropriate response in either Atom or JSON (JavaScript Object Notation) format, and 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. The utilization of these HTTP requests allows for the use of these REST endpoints to perform typical CRUD (create, read, update, and delete) operations against SharePoint entities like SharePoint sites or lists.

The URI (uniform resource identifier) for these REST endpoints closely mimics the API signature of the resource in the SharePoint client object model, as the main entry points for the REST service represent the site collection and site of the specified context that is submitted. To provide an overview of this, a specific site collection can be accessed by using the following:

http:// server / site /_ api / site

If you are wanting to access a specific site, you would do so by using the following:

http:// server / site /_ api / web

The server always represents the name of the server and the site represents the name of the site or the path to the specific site. By using this as a baseline, you can then construct more specific REST URIs by utilizing the object model names of the APIs from the client object model separated by a forward slash (/).

The differences between a URI, a URN, and a URL can be confusing due to the similarities of the concepts of all three of these terms.

A URI is a uniform resource identifier, which is a string of characters used to identify a name or a resource on the Internet. A URI identifies a resource by location, by name, or both. A URI has two specializations known as URL and URN.
A URL is a uniform resource locator, which is a subset of the URI. The URL specifies where an identified resource is available, as well as the mechanism for retrieving it, and defines how the resource can be obtained.
A URN is a uniform resource name is actually a URI that uses the URN scheme but does not imply availability of the identified resource.

This means that both URNs (names) and URLs (locators) are URIs, and a specific URI may be both a name and a locator at the same time.

To clarify this in an example, EPC Group is the consulting firm that I work for and the name “EPC Group” can be used as an “identification.”

There are also a few firms overseas named EPC Group but they are in manufacturing and in other business verticals; so just telling you the company name “EPC Group” does not provide you any specifics on just the face value of the “identification” provided.

Think of the differences, in terms of performing a Bing or Google search, between the terms “EPC Group” and “EPC Group SharePoint Office 365 Houston.”

The second search term provides additional metadata, which then will provide more specifics to identify the correct company and its location.

A URN is very similar to a name and a URL is similar to a street address; the URN defines the actual identity whereas the URL provides a location. So in summary, a URL is a URI that identifies a specific resource and also provides the means by which you can locate the resource by describing the way to access it.

The REST APIs and OData in SharePoint
REST APIs in SharePoint are now compatible with OData, the industry standard for creating and consuming data APIs. The official reference for OData, as well as to track updates regarding this industry standard, can be found at the following link: http://www.odata.org

OData’s official description, in essence, states that OData builds on core protocols like HTTP and commonly accepted methodologies like REST, resulting in a uniform way to expose full-featured data APIs.

In terms of SharePoint, OData is a protocol for interacting with RESTful web services. It was released under Microsoft’s open specification promise; it works on top of standard HTTP using HTTP GET, POST, PUT, and DELETE verbs and returns standard ATOM or JSON formatted results.

For more information regarding Microsoft’s open specifications promise, refer to the following link:


RESTful web services are basically those services or applications that conform to REST constraints, and any service that does not conform to the required constraints should not be considered RESTful.

There is a very strong focus on resources within RESTful web services and they should be simple for a developer to utilize. These services should follow these four principles:

  • Utilize HTTP methods appropriately
  • Expose data in a directory structure
  • Be stateless
  • Transfer either XML or JSON formatted results, as shown in the images below


Microsoft has also recently released a 300-plus page OData/open specifications whitepaper for protocols, file formats, languages, and standards, as well as overviews of the interaction among each of these technologies, which can be accessed at the following link:


REST and Search in SharePoint

The new Search capabilities in SharePoint include a Search REST service that you can utilize to add search features and functionality to your organization’s client applications as well as your mobile applications that support REST web requests.

This capability enables you to use the Search REST service to submit Keyword Query Language (KQL) or FAST Query Language (FQL) queries in apps for SharePoint, mobile apps, and remote client apps. In addition, the new Search REST service also supports both HTTP POST and HTTP GET requests.

For GET requests, you would construct the URI for query GET requests to utilize the

Search REST service by using the following:


The GET request specifies the query parameters in the URL and can utilize two options for constructing GET requests as detailed here:




For POST requests, you would construct the URI for query POST requests to utilize the

Search REST service by using the following:


The POST requests are passed via the query parameters in the request in JSON format, and the HTTP POST version of the Search REST service supports all the parameters supported by the HTTP GET version.

You should utilize POST requests whenever the following is true:

You have concerns about the length of your URL due to URL length restrictions that may be experienced with a GET request.
You cannot specify the query parameters via a simple URL such as those in pass parameter values that contain a complex type array because there is added flexibility around the construction of POST requests.

You must ensure that whenever a call is made to the Search REST service, the specific query parameters are included with the request because these query parameters are used to construct the underlying SharePoint search query.

These query parameters are specified in different manners between GET and POST requests:

  • GET requests specify the query parameters in the URL.
  • POST requests pass the query parameters in the body in JavaScript JSON format.


Source: dotnetsharper





Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s