Understanding SharePoint’s REST API Part 1 – Selecting Items.note

Source: /Volumes/X9 Pro/ObsNotes/YoudaoYunNotes/默认笔记本/Understanding SharePoint’s REST API Part 1 – Selecting Items.note.pdf Converted: 2025-12-10 12:19:25

---

Understanding SharePoint’s REST API Part 1 –

Selecting Items

By Michael Soriano in

SharePoint 2013 has a REST API that exposes plenty of information about users, lists and document

libraries. For front end developers, this is a gold mine. A gold mine because of two things: 1) SharePoint’s

out of the box UI is pretty bad, and 2) SharePoint’s out of the box UI is pretty bad.

So plenty of room for improvement here. Now we can basically recreate SharePoint’s front end: entire new

CRUD interfaces and such. And the base of it all – is its REST API.

It is important to recognize that SharePoint is using , which is a widely used convention when in

comes to RESTful web services. You can learn more about the syntax from their website.

For this post I would like to cover Selecting Items.

Note that I prefer using jQuery’s $.ajax method. So all my calls will look like below:

All we’re doing is replacing the url

If you’re still on SP 2010 the querystring section of the examples below may be the same. The only

difference I’ve seen is the endpoint part of the url. SP 2010 has below:

Selecting all items, all columns

The simplest way to grab list items is to get everything. This is done by using the endpoint below. Simply

change the “list” value to your own:

Again, this will select “almost” all columns that are available to the list. Note that I said “almost”, because

the API doesn’t really bring back everything. Things such as author information and values of lookups have

to be queried differently (more on this below).

Selecting all items, custom columns

I find it good practice to only grab the columns that I need. This makes the payload as lean as possible.

Snippets January 16, 2016 5 Comments

OData

1

2

3

4

5

6

7

8

$.ajax({

url: url, //THE ENDPOINT

method: "GET",

headers: { "Accept": "application/json;

odata=verbose" },

success: function (data) {

console.log(data.d.results) //RESULTS

HERE!!

}

});

1 _spPageContextInfo.webAbsoluteUrl +

"/_vti_bin/listdata.svc/" + querystring

1 _spPageContextInfo.webAbsoluteUrl + "/_api" +

"/web/lists/getbytitle('listname')/Items?$select=*";

This also makes it easier to find things because each Javascript object only contain the columns “ID” and

“Title”. What I don’t understand is why “ID” and “Id” is present – maybe a configuration error with the list. But

nevertheless, the result is more manageable:

Getting the total items in a list

To get the number of items in a list, append the “ItemCount” in the end of your query sting.

I know that you can simply do a “.length” from the a regular call which brings you all of your results, but the

above is useful for filtered results, or when paging. The output looks like below:

Retrieving specific list items

Now this endpoint will only get the list item with the ID of “4” (I’ve removed the

“_spPageContextInfo.webAbsoluteUrl” component for easier read…

A more powerful solution is using the $filter key. Not that this option allows you to get items with more

flexibility. Check out this example which grabs items with the title equals to “example 1”. Note the use of

single quotes!

Multiple $filter keys + values

1

_spPageContextInfo.webAbsoluteUrl + "/_api" +

"/web/lists/getbytitle('listname')/Items?

$select=ID,Title";

rest-select-1

1 _spPageContextInfo.webAbsoluteUrl +

"/_api/web/lists/getbytitle('listName')/ItemCount

item-count1

1 /_api/web/lists/getbytitle('listname')/items(4)

1 /_api/web/lists/getbytitle('listname')/Items?

$select=Title&$filter=Title eq 'example 1'

To get items that have Title that is equal to multiple values, use the endpoint below:

Notice that I used parenthesis to enclose the multiple parameters. This is completely optional – but

improves readability.

In the case of multiple “ANDs” and “ORs”, for a stricter and finer result set, you need to use the parenthesis

to enclose filter sets. This example below:

You see how we’re grabbing items with “ContentType” equaling to “Operating Policy” OR “Procedure” AND

“Subject” equaling to “Safety”.

Limiting your results

The $top parameter basically limits your items to a specified number. The syntax is below:

This is also useful for creating paging systems – in combination with an offset option (below).

Offsetting results (for paging)

So you know how to limit your results, and you know how to get the total items. All you need is to offset your

results. You do this with the “$skip” parameter.

Again, note the use of single quotes. The above will get a set of 10 items, starting from the 20th in the list.

Combined with the total, you can create your own paging mechanism.

Update 8/10/2016: I just found out that the with list items. There is a property

in the REST response that you can use – for paging. This is known as the “___next”. I will do another

tutorial strictly on this subject – so stay tuned.

Getting the Author Information

You have to specify that using the “$expand” key. Also an additional parameter to the “$select” key is

needed. For example, to grab the Id and the name of the author, simply append to your query:

The above will return the author information in it’s own node called “Author”.

1

/_api/web/lists/getbytitle('listname')/Items?

$select=Title&$filter=((Title eq 'example 1')

or (Title eq 'example 2'))

1

/_api/web/lists/getbytitle('ListName')/Items?

$&$select=Title&$filter=((ContentType eq

'Operating Policy') or (ContentType eq

'Procedure')) and (Subject eq 'Safety')

1

_spPageContextInfo.webAbsoluteUrl +

"/_api/web/lists/getbytitle('listname')/Items?

$select=Title&$top=10";

1

_spPageContextInfo.webAbsoluteUrl +

"/_api/web/lists/getbytitle('listname')/Items?

$top='10'&$skip='20'"

$skip parameter doesn’t work

1

_spPageContextInfo.webAbsoluteUrl +

"/_api/web/lists/getbytitle('listname')/Items?

$select=Author/Title,Comment&$expand=A

uthor/Title

Document Libraries

Querying lists that are document libraries – for the most part, are handled through the same endpoint.

The example above returns information about your file such as the name, full url and the internal “Title”:

For instances where you want to know the “type” of document library it is (example Picture Library vs

Document Library), use:

Although some information regarding document libraries require an entirely new endpoint. This includes file

paths, subfolders, thumbnails and such.

The above contains an entire new set of information regarding your library.

Getting Current User information:

At times you want to grab the current user’s information. Use the endpoint below:

Again, there may be additional information that is not returned by the above (such as roles). This may not be

supported, or requires a different endpoint.

rest-select-2

1

_spPageContextInfo.webAbsoluteUrl +

"/_api/web/lists/getbytitle('Document Library

Name')/Items?$select=Title, FileLeafRef,

EncodedAbsThumbnailUrl, EncodedAbsUrl

rest-select2

1

_spPageContextInfo.webAbsoluteUrl +

"/_api/web/lists/getbytitle('Document Library

Name')/BaseTemplate

1

_spPageContextInfo.webAbsoluteUrl +

"/_api/web/GetFolderByServerRelativeUrl('"Folde

r Name"')/Files"

1

_spPageContextInfo.webAbsoluteUrl +

"/_api/SP.UserProfiles.PeopleManager/GetMyPr

operties"

The __metadata object

You will notice that each result will have this __metadata object tied to it.

This contains important material that will help you later in update and delete operations. I’ll cover that in the

next chapter.

Conclusion

As I’ve mentioned, SharePoint’s REST API has some very powerful features. And with OData’s standard’s,

you can create quite advanced queries. I will try to keep this article updated with more Select related

queries, but for now I have to go. Stay tuned for the next part.

3rd-screenshot-rest