Learn About SharePoint REST API

In this article, we will understand the basics and capabilities of SharePoint REST API

Before we dive into Rest API let's talk about API.

API stands for Application Programming Interface. it is not necessary that API must be web-based. It can be web-based or local or operate within a single system or network. API is a set of rules and protocols which is used to communicate with different software applications.

Example. suppose that we have a meeting with one organization, and in that organization, many people know different languages according to their region, but there is one common language that all members who are present in the meeting know and that language is English, so English is a protocol, and it makes sense to deliver knowledge to all of them.

Now, let's take a technical example; we all use YouTube in daily life for educational purposes or entertainment purposes. Now, suppose that YouTube is a video player that is developed in Python, the comments section developed in React, and the like and dislikes functionality developed in Java, so what is the common thing that makes this functionality communicate to each other for data transfer? That is API which is common for all technologies or software applications to communicate to each other.

What is a REST API?

REST API: stands for Representational State Transfer Application Programming Interface.

REST API is a set of rules and conventions for building and interacting with web services. REST API uses standard HTTP/HTTPS protocol methods like get, put, post, delete, and patch. In REST API everything is considered as a resource. And those resources are identified as URLs like ‘http//api.exc.com/users/989’.

Now we all get updates for weather forecasts from news Applications or any weather department. If we want to develop our own weather forecast app, then we need to put our own satellite in space, and then analyze and fetch data for weather forecasts. But it is now possible, right ?! So there is REST API for weather forecasts, which is used commonly in all weather forecast apps and news and this REST API is shared by the weather department that APIs give updates about weather forecasts.

So in this weather forecast API, we use standard methods like,

GET: to fetch weather forecast data for day, week, or month.
POST: you send data to weather services to update your preferences or send data that necessarily doesn’t fit your preferences.
PUT: you update your existing information, like changing your city location or other settings for your preferences with existing information.
DELETE: to delete data or information from the server or from weather service.

What is SharePoint REST API?

As we discussed about REST API, SharePoint also provides REST API, which is used to interact with SharePoint data. It provides endpoints to perform CRUD (Create, Read, Update, Delete) operations on SharePoint objects.

Now, we will discuss the key benefits of SharePoint REST API.

Platform independence: SharePoint REST API supports any technology stack that supports HTTP/HTTPS protocols. It can be used on various platforms and different programming languages or frameworks as long as they support HTTP protocol. This flexibility allows developers to integrate the software into diverse systems easily.
Flexibility: SharePoint REST API allows interaction with various SharePoint components such as lists, sites, users, and libraries. This means that it can manage and manipulate different types of data and functionality within the SharePoint environment, providing versatility and comprehensive support for various tasks and processes.
Efficiency: in this context means that it minimizes the need for writing complex code on the server side. This can streamline processes, reduce errors, and improve performance by handling many tasks that need backend programming.
Standardization: refers to the use of widely accepted protocols and methods that ensure consistency and compatibility. SharePoint REST API uses standard methods such as GET, POST, PUT, and DELETE. Which ensures that it interacts seamlessly with web services and APIs.

Basics Terminologies of SharePoint REST API

Endpoint: It is a URL. By using it, REST API services can be accessed. An endpoint is a specific URL or address in which an API can be accessed by a client and can operate by creating, updating, retrieving, and deleting resources.
HTTP Methods: HTTP standard methods are used to perform operations like GET to retrieve data, POST to create new data or entries, PUT to update existing data or entries, and DELETE to remove data or entries.
OData: Open Data protocol which is used to query and update data. OData is a standard protocol that allows users to create and consume REST-based services. OData allows users to access information from a variety of resources. And publish and edit resources. It's built on core protocols like HTTP and uses commonly accepted methodologies like REST for the web.
JSON: stands for JavaScript Object notation, a lightweight data-interchange format used by REST APIs. JSON is a text-based format used to represent structured data. It is commonly used by REST API to transfer data between client and server due to its ease of use. Although JSON is language-independent it would be well-suited to use with JavaScript or its framework.

Structure of a SharePoint REST API Request

Now let's look into the structure of SharePoint REST API

Base URL: ‘https://your-domain.sharepoint.com/_api/ ’
Resource Path: Specifies the SharePoint resource (e.g. ‘ web/lists/getbytitle(‘Listname’) ’)
HTTP Method: Determines the action to be performed (GET, POST, etc.)
Headers: Include authentication and content type (e.g., 'Authorization: Bearer <access_token>', 'Accept: application/Json’).
Example: GET https://yourdomain.sharepoint.com/_api/web/lists/getbytitle('Tasks')/items

Now we will discuss authentication and permission

Authentication & Permissions

This is a process of verifying user identity or application accessing the SharePoint REST API. SharePoint REST API supports various authentication methods and then grants permissions according to successful authorization. There are many methods but we will discuss commonly used methods such as,

OAuth: it is a token-based authentication system where users or applications get an access token which makes authenticated API requests. This access token carries the user or application permissions. Which dictates what resources and operations can be accessed in SharePoint. OAuth supports both user-level and app-level permissions.
App Only: this method allows with own ID such as client ID and client secret to authenticate. Permissions are granted when app registration. These permissions are broad and enable the applications to perform tasks across SharePoint, such as automated workflows, background services, or integration.
User Context: this method is based on users' logged-in user credentials. Users log in authenticate, and get an access token that includes their user identity. That token reflects the user`s permission to SharePoint. This means that any API call by the user that is authenticated requests constrained permission by itself.

Some Common Endpoints and Operations

Site Information: GET /_api/web
List Information: GET /_api/web/lists/getbytitle('ListName’)
List Items: GET /_api/web/lists/getbytitle('ListName')/items
Create List Item: POST /_api/web/lists/getbytitle('ListName')/items
Update List Item: POST /_api/web/lists/getbytitle('ListName')/items(<item_id>)
Delete List Item: DELETE /_api/web/lists/getbytitle('ListName')/items(<item_id>)

Here we have the basic example and in what format it responds.

Request: GET https://your-domain.sharepoint.com/_api/web/lists/getbytitle('Tasks')/items
Response

 {
    "id": {
        "results": [
            { "Title": "Task 1", "Id": 1 },
            { "Title": "Task 2", "Id": 2 }
        ]
    }
}

Example. Creating a List Item

Request

POST https://your-domain.sharepoint.com/_api/web/lists/getbytitle('Tasks')/items
Content-Type: application/json;odata=verbose

 {
    "__metadata": { 
        "type": "SP.Data.TasksListItem" 
    },
    "Title": "New Task"
}

Response

 {
    "d": {
        "Title": "New Task",
        "Id": 3
    }
}

Handling Errors

HTTP Status Codes:200: OK
201: Created
400: Bad Request
401: Unauthorized
403: Forbidden
404: Not Found
500: Internal Server Error

Error Response Format

{
  "error": {
    "code": "code",
    "message": {
      "lang": "language",
      "value": "error message"
    }
  }
}

Advanced Features

Batch Processing: this feature is great for dealing with multiple requests. It improves performance by reducing the number of HTTP requests needed.

Query Option

Use ‘ $filter ’, ‘ $select ’, ‘ $expand ’, and ‘ $orderby ’ to refine data retrieval.

$filter: used to specify criteria to filter the results.
$select: determines which fields should be included in the response.
$expand: includes related entities and navigation properties in the response.
$orderby: Orders the results based on specified criteria.

Metadata: this is the additional data about the data you’re working with, so it helps us to how to use and manipulate it more effectively.

Tools and Resources

Now let's talk about tools and resources to use SharePoint REST API,

There is no specific tool to use SharePoint REST API or any tool that supports HTTP/HTTPS protocols. It is able to be used for SharePoint REST API. Such as,

Postman: For testing API requests.
Fiddler: For capturing and analyzing HTTP traffic.
SharePoint Documentation: Official Microsoft documentation for in-depth reference. SharePoint REST API documentation

Conclusion

In this article, we have seen that SharePoint REST API is a powerful tool for interaction with SharePoint data. We have seen error codes while working with APIs, and if there are any errors, we need to identify them. SharePoint REST API Provides a flexible, efficient, and standardized way to perform CRUD operations. Understanding the basics, best practices and advanced features can greatly enhance your ability to work with SharePoint.