For readers out there that don’t know much about SharePoint, let’s briefly go over the main aspects of what it is and what it intended for. Microsoft created a tool back in 2001 in an effort to offer a collaboration environment that organizations of all sizes could use to increase the efficiency of business processes. Essentially this was a centralized place to primarily serve as a document management and storage system for professional environments.
However, for years it was notoriously bashed since the application offered businesses little options to brand and construct the site to best suit their needs. An out of the box, what you see is what you get sort of product. But over the years the web based app improved along with the documentation and it is now highly configurable and can offer organizations fantastic possibilities when it comes to customizing and displaying content in a unique and brand conscious way. Not to mention a business can now have a user-friendly, CMS type intranet that loads content dynamically onto site pages.
This blog is tailored to show you a few of the possibilities on how to use jQuery AJAX with the SharePoint Rest API to display content from custom lists in the admin section on to an internal page.
How the REST Service Works
This post is assuming you have basic familiarity with REST and how to write requests within jQuery. SharePoint, 2013 specifically, 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, using the Open Data Protocol (OData) standard, which corresponds to the desired client object model API. A simple example of this request would be:
Client object model method: List.GetByTitle(listname)
The client.svc web service within SharePoint handles the HTTP request, and serves the proper response in either Atom or JSON format. After than the client application must then parse that response.
Getting Specific with Your Requests
An awesome benefit to using HTTP requests, is that you can use these REST endpoints to perform classic CRUD operations against SharePoint entities, such as lists and sites. Below is a REST endpoint example on how to interact with the data and retrieve a specific list based off of its title:
As you can see from the ending line, we are returning back the data in XML format. By appending the url with “/items” we can essentially retrieve all of the items within the list we targeted. Example:
Something to note is if the $select option isn’t used, all fields are returned except fields that would be resource-intensive for the server to return. If you need these fields, you need to use the $select option and specify them by name.
This basic idea also works for folders, files, and documents within your SharePoint site. You can even drill down further after getting the items in that list by targeting column names (i.e. Title, Employee, company in the example code below) within that list in addition to sorting the data you receive in alphabetical or date created order. There may be an instance when you only want to show the latest 5 items created in the list and using the $top option can help you achieve that. Let’s go over some of the helpful query options you have when using REST requests.
Select Items to Return
Append your url with the $select parameter to get only the specific desired columns/fields
Append your url with the $filter parameter to retrieve only items that match a simple logical expression
Append your url with the $top operator to limit the number of results to return
Append your url with the $expand operator to get back a corresponding value based on and Id
Append your url with the $orderby parameter to sort the results from the list
If you haven’t gathered by now, there are countless options to drill down into a specific list and display the filtered items you want all by using the correct syntax within your jQuery AJAX calls. The next step after writing the necessary code would be to link your script on either the master page or if you have numerous scripts that target many lists it is probably best to add the script tag that links to your file with a content editor web part on the desired page. Happy SharePointing!