Comprehensive Reference
SharePoint REST API Endpoints
Before You Begin
I am sure that you are aware of API but if in case you are quite new to APIs and its usages, I have provided an overview below.
However if you are here to know only about SharePoint REST API then click here to jump to SharePoint REST API reference section.
#. What is an API?
API is an abbreviation of Application Programming Interface
You can think of API as an intermediary between two applications or devices. It helps them to talk with each other.
According to Wikipedia: an application programming interface (API) is a connection between computers or between computer programs. It is a type of software interface, offering a service to other pieces of software.
In contrast to a user interface, which connects a computer to a person, an application programming interface(API) connects computers or pieces of software to each other.
#. What is the use of API?
One purpose of APIs is to hide the internal details of how a system works and exposing only those parts which a programmer will find useful. Also, if any inside logic changes then programmer do not need to worry about as the API will remain the same and fulfil the same purpose.
An API also helps to leverage core functionalities of an application from another applications thus increasing reusability.
For example: If you want to send an email then, instead of writing an entire email application, you can simply call any existing email API to send an email.
#. Examples of API
APIs are everywhere & we cannot live without them.
We are using API on a daily basis, i.e. when logging into your Gmail account, or when searching for a location in Google/Bing map, or even when trying to search for a YouTube video. All of these requests are served to you via APIs
#. Types of API
APIs can be broadly categorized based on two things
- Depending upon their access
- Internal API – only available to internal employees or a software and not accessible by others
- Partner API – This is kind of open API but you need to have a unique Auth code to use the APIs
- Open API – this kinds of APIs are available to everyone. i.e. Google Map location search
- Depending on the Protocol used
(Though there are more types of API Protocols but I have mentioned only two here)- SOAP API – Simple Object Access Protocol is an API protocol built with XML, enabling users to send and receive data through SMTP and HTTP.
- REST API – Representational State Transfer or RESTful API, a flexible, lightweight way to integrate applications.
#. Components of API
It is important to note that any API request is made of four parts as follows
- The endpoint
- Requirement: Mandatory
- Purpose: It is the URL(or path) of the API. This defines where to go and look for information
- Method
- Requirement: Mandatory
- Purpose: It defines what the API is trying to do, i.e. read, edit or delete
- Header
- Requirement: Mandatory (almost)
- Purpose: This is responsible for passing information such as email id, passwords or Auth tokens etc. If the API is open and do not require any authentication then header can be empty as well. However, most of the times we need to specify it.
- Body
- Requirement: Both, mandatory & not mandatory
- Purpose: This part carries the information which we are trying to save/put in the server. For example, when we are trying to update an item in the DB(server) then this part will carry the latest details of that item and the API will help save this information.
All of these are again discussed later (for SharePoint API)
SharePoint APIs – Reference & Examples
Overview
SharePoint API endpoints helps other o365 application or 3rd party applications to communicate with SharePoint site and its features. The most commonly used SharePoint APIs are .NET client-side object model (CSOM), JavaScript object model (JSOM), and REST API.
How it works: 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.
Some of the common use of SharePoint APIs are
- Upload files to SharePoint document library automatically
- Fetch/update details from SharePoint lists and libraries
- Setup custom permission in a library or a file
- Add or remove user from SharePoint site
#. Examples of SharePoint API
Some examples of SharePoint API endpoints are
- _api/web/lists – returns an array of lists in the SharePoint site
- _api/web/lists/getbytitle(‘list_name’) – returns details of a particular lists
- _api/web/lists/getbytitle(‘list_name’)/items – returns all the items in a particular list
#. SharePoint API Methods
SharePoint API has the below CRUD operation methods.
- GET – Read a resource from SharePoint
- POST – Create or update a resource in SharePoint
- PUT – Update or insert a resource in SharePoint
- DELETE – Delete a resource from SharePoint Site
To learn more, check Microsoft documentation on SharePoint API methods
#. SharePoint REST API in details
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 basic/barebone structure of SharePoint API is: https://{site_url}/_api/{resource_path}
The above API has two main components Service Root URL and Resource Location. However it does not include the other mandatory component, i.e. the method (GET, PUT) component. So if you do not see the method mentioned in an example, then you can consider that GET method is used.
# What is Service Root URL?
Service root URL, is the root(or main or basic) URL for the API. This is common for the all the API resources in an applications. All the API endpoints come under the service root URL and can be accessed by through the corresponding resource path.
for SharePoint online site the service root URL is: https://{site_url}/_api
# Resource Path
Resource path is unique path to a particular type of resource and is responsible for returning the corresponding value/data. You will understand more as you progress further. As of now, understand that, resource path is the location where you can put/get some data.
As an example(resource path in bold): https://{site_url}/_api/web/lists
In the above API example, I am trying to access the lists resource which is under web. Executing this API successfully will return all the lists in a particular SharePoint site.
# Query Parameters
Query parameter is added at the end of an API URL. an example is shown as shown below (in bold)
https://{site_url}/_api/web/lists?$top=1
The query parameters are always placed after a question mark and are separated by ‘&’ symbol.
The query parameter in the above example is $top=1 . This query parameter is responsible for returning only the first item from the list of results. There are many other query parameters such as
$select – is used to select only particular columns from the source
$filter – is used to filter your results with some conditions
$skip, $count, $search and many more
One important point, you can add multiple query parameters, separated by an & sign like the below line,
?$query1=value1&$query2=value2
and so on
Also to note, in addition to the optional query parameter, the information provided in the body of an API request may be passed as query parameter as well.
SharePoint REST API Examples
To show the examples, I am using
Power Automate >> Send a HTTP Request to SharePoint block
With the help of SharePoint API we can perform many different kind of actions, such as Fetch item details, update file/item properties, delete a file and many more. Here I have shown a few examples
#Overview – Power Automate Send HTTP Request
If you are unaware of Power Automate and not sure about its capabilities, please check this beginners guide.
The Send HTTP request to SharePoint block is a good option to test SharePoint APIs as it does not require any authorization code. And hence you do not need to worry about the header. However, if you are familiar with other API tools such as POSTMAN, then feel free to use them as well. Anyhow, for the below examples, I am using Power Automate
#1 – API to Fetch Item Details from SharePoint List
This example shows how to fetch item details from a SharePoint list. The API details are as below
endpoint: _api/web/lists/getbytitle(‘List_name’)/items(item_ID)
method: GET
header: accept – application/json;odata=nometadata
body – Note applicable for this request
#2 – API to Update Item details in SharePoint List
This example shows how to update SharePoint item properties through SharePoint API. The API details are as below
Endpoint: _api/web/lists/getbytitle(‘List_name’)/items(item_ID)
Method: POST
Header:
Accept: “application/json”
Content-Type: “application/json”
If-Match: “*”
X-HTTP-Method: “MERGE”
Body: {
“required_column_1”: “value1”,
“required_column_2”: “value2”,
“required_column_3”: “value3”
}
#3 – API to Delete item from SharePoint List
Deleting an item using API in SharePoint is very simple. It is similar to getting item details but the method is “Delete” instead of “Get”. Below are the API details
Uri: _api/web/lists/getbytitle('list_name')/items('id')
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
If-Match: "*"
X-HTTP-Method: "DELETE"
#4 – SharePoint API – Create A List item
To create a list item you need to call a POST API with the below details
Uri: _api/web/lists/getbytitle('list_name')/items
Accept: "application/json;odata=verbose"
Content-Type: "application/json;odata=verbose"
body: {
"__metadata": {
"type": "SP.Data.TestListItem"
},
"Title": "Test"
}
# Need More Examples?
I hope you have enjoyed this document so far and if you are still looking for more reference on SharePoint REST APIs then please check our other posts related to SharePoint APIs listed below. Each these documents provide a comprehensive guide on a particular application of SharePoint REST API. And at last, please keep checking our posts as we are regularly releasing new guides and are planning to release few more documents on SharePoint REST APIs
Well, that’s all I have for this beginner tutorial for SharePoint API. If you want to learn more, check this Microsoft document or check my advanced tutorial on SharePoint REST API.
I hope you have found this helpful and learned something new.
Please Help us Grow!
I hope you have found this article helpful. If you are happy with the document, please use the below links when you buy something from Amazon to help us grow.
Ways to Help
Amazon Affiliate Links
How this works?
Amazon affiliate program gives a small (%)share of price to the referrers, so feel free to buy anything.
Below are some Amazon affiliate links, if you open amazon application/website using these links and buy something, (it can be one of the below items or anything of your choice) Then Amazon will give us a little percentage(%) of the money you spend on Amazon. To know more check this document.
Thank you
For your Contribution
Newbietechie.com
Author @ramizmollahmd
About Ramiz
Ramiz is a professional working in an MNC as a business and technology consultant for quite a few years now. Ramiz is proficient in various Microsoft tools and technologies. He is a tech enthusiast and an active blogger. Ramiz spends his free time playing games or watching movies. He writes blogs to share his knowledge with the world and to make it a better place to live.
Pingback: Create a SharePoint site using REST API [Power Automate]
Pingback: How to generate API Access Token for SharePoint [POSTMAN]
Pingback: Top 11 SharePoint Developer Interview Questions with Answers