Moving from SPServices to REST, Part 1: Introduction

This entry is part 1 of 6 in the series Moving from SPServices to REST

In this series, you’ll learn how to transition from the SOAP Web Services – which SPServices supports – to REST. If your organization is making a transition to SharePoint 2013 or Office 365 & SharePoint Online (and anything hybrid in between), this series will help you develop new patterns, migrate your codebase, use OData effectively and more.

It’s been a nice, long ride for SPServices. If you aren’t familiar with SPServices, it’s freely available on Codeplex, Microsoft’s waning open source repository.

SPServices is a jQuery library that abstracts SharePoint’s Web Services and makes them easier to use. It also includes functions that use the various Web Service operations to provide more useful (and cool) capabilities. It works entirely client side and requires no server install.

The Web Services that SPServices abstracts for you are the older SOAP Web Services, sometimes known as XML services, or ASMX services. As I’ve said repeatedly at conferences and in posts (like this one) before, I think we still have many miles to go with the SOAP Web Services. Microsoft officially “deprecated” the SOAP Web Services as of the launch of SharePoint 2013, but I can’t see them fully disappearing for a good long time given the number of different ways they are used.

Two API sets are still supported in the SharePoint 2013 framework for backward compatibility, but we recommend that you not use them for new projects: the ASP.NET (asmx) web services, and direct Remote Procedure Calls (RPC) calls to the owssvr.dll file.

See: https://msdn.microsoft.com/en-us/library/office/jj164060.aspx#DeprecatedAPIs

I started writing this series just after SPTechCon San Francisco in 2014, having talked to Andrew Connell and Scot Hillier about how I might be able to contribute to IT Unity for the site’s launch. Obviously the series fell by the wayside for quite a while, but these topics are even more relevant now than they were when they first came to me.

Like many of you, I drive an older model car. It is fun to drive, is comfortable and seems to be in great shape. The car may last me a while, yet from time to time I think about what I might want to drive next.

Moving from SPServices to REST is like deciding to trade in your reliable car for a model with more safety features. You should do it, eventually.

Photo Credit: “FIAT 600” by Andrea~S on Flickr http://ow.ly/wqxGN

At some point, we’ll all want to head into the dealer and get ourselves something shiny and new. To me, that something new is REpresentational State Transfer, also known as REST.

While SharePoint’s client-side object model (CSOM) can do a lot, it’s a SharePoint-specific technology. REST, however, is a Web standard. Many Web developers use REST to get their work done every day outside the SharePoint world. It’s time for those of us who develop on top of SharePoint to catch up with the rest of the Web development community. Most SharePoint developers have caught onto this reality in the last year or so.

When REST was first offered as an option in SharePoint 2010, it let us get some work done with lists, but that was about it. With SharePoint 2013 and even more so on Office365 with SharePoint Online and the Office365 APIs, the SharePoint team at Microsoft continues to give us more and more RESTful – or REST-driven – capabilities. New REST services have been introduced regularly and the existing services have been extended many times.

If you’ve loved working with SPServices, or at least you’ve gotten some good work done with it, this series of articles will help you to make the transition from the SOAP Web Services that SPServices wraps to the more open – and undoubtedly more robust over time – REST services offered in SharePoint 2013 and Office365. If you’re still running SharePoint 2007 or 2010 – as I know many of you are – this should still be a valuable series to you. By making some adjustments in your development style and the coding patterns that you follow, you can put yourself in an excellent position to move to REST when it becomes appropriate for you to do so.

Here are some of the things I plan to cover in this series:

  • New patterns I suggest you follow with your SPServices code so that you’ll be better prepared to move to REST when the time comes. A side benefit of these new patterns will be better modularity and reusability in your SPServices-based code.
  • You will learn ways to move parts of your code from SPServices to use REST even now with less effort than you might think. We’ll talk about where the most likely places in your codebase probably are and how to get started.
  • We’ll look at how the functionality in the SOAP Web Services maps to the current REST services and where there are still gaps.
  • We’ll talk about where OData comes in and how best to understand the OData componentry that sits under the SharePoint-specific implementation of REST. There are some differences from the standard (these gaps are narrowing all the time), and it’s important to know what those differences are and why they matter.
  • As Microsoft adds more functionality to REST in SharePoint 2013 and Office 365, I’ll write new articles in the series to augment the base set of content. It’s not your father’s Microsoft anymore – the SharePoint team is moving fast and improvements are going to be coming Fast and Furious (see what I did there?)

It’s hard to give up the old car that you’ve driven for years, but sooner or later, it’s time. Maybe the engine starts knocking too much or the springs in the seat get uncomfortable. Maybe you just want to try out something new. It is sad letting the old girl go, but at some point, it’s simply time. I once held onto a car until the engine simply stopped working. You don’t want to be in a similar situation with your SharePoint functionality built on top of SOAP. Let’s start to plan for the future, and let’s do it together.

Cooler with better design and safety features. Your new code using REST, using practices favored by the rest of the Web development community.

Photo Credit: “2014 Fiat 500” by Abdullah AlBargan on Flickr http://ow.ly/wqynJ

This article was also published on IT Unity on March 25, 2015. Visit the post there to read additional comments.
Series NavigationMoving from SPServices to REST, Part 2: New Patterns for SPServices Development >>

9 Comments

  1. Marc, this is great and I can tell already this series is going to be a valuable SharePoint gem for many years to come. The fact that you’re willing to do this as the creator of the awesomeness that is SPServices is mind-blowing. Once again shows what a refreshing, inspirational, humble and forward thinking leader you are. More power to you and I can’t wait to see what you’ve got next!

    Reply
  2. Hi Marc, I have to agree with Joel on this!

    You led the SharePoint world to client-side development, and really delivered the goods by providing SPServices. My guess is there are more solutions built on SPServices than REST and JSOM combined, and probably will be for some time.

    It’s great to see you embracing the change and continuing your thought leadership. A lesser man might try to perpetuate his work by fiat. You’re the best; thanks!

    Reply
  3. Great analogy on the Fiat 500! I’m not a big shot like Andrew Connell, but I’d be willing to collaborate on a new REST-based library that could get any close to the functionality of SPServices.

    Reply
      • I really look forward to the series, thank you. The top 5 operations I use on any project are:

        1) GetListItems
        2) GetListItemChangesSinceToken
        3) GetUserInfo
        4) UpdateListItems
        5) SPGetListItemsJson

        I’m also very interested on the impact, if any, with CAML queries.

        Reply
      • Sorry about this delay – I didn’t get a notification on the reply. Well, SPGetListItemsJson is a great one. REST calls do some of its job, but I guess SPServices could have a parametrized utility to make some of the redundant ajax work easier. I find the ones on user data to be really useful. SPCascadeDropdowns is also essential. It might be hard to pick. Maybe a survey on uservoice could help.

        Reply

Have a thought or opinion?