Understanding SharePoint’s REST API Part 1 – Selecting Items

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 OData, 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

A special note on SP 2010 users: 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:

1) 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).

2) 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.

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:

rest-select-1

3) 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:

item-count1

4) 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!

5) Multiple $filter keys + values

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”.

6) 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).

7) 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 $skip parameter doesn’t work 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.

8) 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”.

rest-select-2

9) 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”:

rest-select2

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.

10) 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.

Bonus: The __metadata object

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

3rd-screenshot-rest

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.

8 Comments

  1. When I run the queries above (namely the all items all columns) the object that is returned in “data” is a Document Object, and it appears to be the entire page’s content. Does this mean I did something wrong?

    My endpoint string is identical with your except for the list name:

    _spPageContextInfo.webAbsoluteUrl + "/_api" + "/web/lists/getbytitle('myTestList')/Items?$select=*";

    Reply
    • Make sure you have all the ajax properties setup:


      $.ajax({
      url: url, //THE ENDPOINT
      method: "GET",
      headers: { "Accept": "application/json; odata=verbose" },
      success: function (data) {
      console.log(data.d.results) //RESULTS HERE!!
      }
      });

      the data object should have d.results – which is another object.

      Reply
      • Hmm. Bizarre. I don’t know what’s different between what I had and what I have now, but it’s returning a data object with a ‘d’ property.

        Thanks

  2. Thanks for the article, this is a nice reference. It says Part 1 in the title, but I can’t find a Part 2, is there one on inserting or updating?

    Reply

Leave a Comment.