Moving from SPServices to REST, Part 1

This entry is part 1 of 1 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 first published on IT Unity on March 25, 2015. Visit the post there to read additional comments.

Great Resource: Responsive SharePoint from Eric Overfield

2015-03-20_10-55-33This week I was working on moving a design into SharePoint 2010. The design was made up of the standard sorts of things: HTML mockups with graphics, CSS, etc. The mockups are using Twitter Bootstrap as the styling framework.

I’ve done this sort of branding implementation many times, and it’s always interesting because what I get to start from is different every single time, even if it comes from the same designer. Over time we all change our approaches and styles because we learn better ways of doing things. That’s a good thing, but it means that every design implementation is like a new experience, albeit with many common components.

When I’m implementing a design in SharePoint, I find that there are use one of three basic approaches, regardless which version of SharePoint it is:

  • From the top down – In this case, I’m changing SharePoint’s master pages very little. We might want to change some colors, fonts, and basic functionality, but it still will look like SharePoint from a structural standpoint: banner across the top, Quick Launch down the left, etc. Here I just make a copy of default.master, v4.master, or seattle.master – depending on the version – and add some CSS and script references.
  • From the bottom up – This is the most extreme branding, where I start with a minimal master page and build things from the ground up. This is most common with Internet-facing sites, but can also be the case for an Intranet. Everything is customized in the master page: the HTML markup, the content placeholders and their placement, etc.
  • Something in between – This was the case with the current project. Even though the end goal is a site that look little like SharePoint, it doesn’t require a total disemboweling of the master page.

For the latter two bullets, we have some excellent choices available to us which have been created by the SharePoint community. To me, the shining lights here are Randy Drisgill (@drisgill), Eric Overfield (@EricOverfield), and Kyle Schaffer (@kyleschaeffer). (That’s an alphabetical list by last name; they are all equally awesome.)

All three of these brilliant guys have free starter solutions on Codeplex:

In this particular project, Eric’s master pages seemed to be the best match. As I was struggling to get the ribbon to behave with Bootstrap, I realized that I didn’t need to fight the battle again myself and that Eric’s master page would probably be just the tickets. Indeed it was! After grabbing his project, I was able to get the design up and running in just a matter of hours.

If you’re even considering coming up with a responsive and/or Bootstrap-driven design, save yourself a lot of trouble and look at Kyle or Eric’s work It probably won’t be exactly what you want out of the box, but they have solved a huge majority of the problems you’ll run into already. This is what makes the SharePoint community so awesome. This is really deep capability and work that is out there for you to use – for free.

 

Synchronous XMLHttpRequest Warning with SPServices and Recent Browsers

If you’re working in the latest versions of Chrome (~40+) – and maybe Firefox – and you use SPServices, you may start to see an warning:

Synchronous XMLHttpRequest on the main thread is deprecated because of its detrimental effects to the end user’s experience. For more help, check http://xhr.spec.whatwg.org/.

Vigilant SPServices user frankhale reported this to me the other day in the SPServices discussions on Codeplex, which is – at least at the moment – the best place to get help with SPServices. You can also add an issue on Github (sympmarc / SPServices) if that’s your fancy.

The warning is thrown in jQuery, not SPServices, but it’s an SPServices issue.

Synchronous XMLHttpRequest on the main thread is deprecated because of its detrimental effects to the end user's experience.

Synchronous XMLHttpRequest on the main thread is deprecated because of its detrimental effects to the end user’s experience.

First off, it’s a warning, not an error. Your code will continue to work in the near term, at least.

Because of some backward compatibility concerns, I’ve left a few synchronous calls internally to SPServices in place. Those calls are what are causing the warning. In particular, it is most likely that the warning is being thrown for you because of a synchronous call on the $().SPServices.SPGetCurrentSite function. The reason for this is that early in the SharePoint 2007 days it was difficult to determine the current site without a call to the Webs.WebUrlFromPageUrl operation. Unfortunately, it seems that I’m making that call in SharePoint 2010 and 2013, even though the current site is available in JavaScript variables.

So, the bottom line is: “Carry on.” I’ll get a fix into the next release of SPServices for this. In the meantime you should be fine.

m4s0n501

The Year That Will Be: 2015

It’s that time of year when people tend to look back at the prior year or look forward to the new one. In my case, I’m generally choosing to look forward. 2014 was a swell year on most counts, but I’m really looking forward to 2015.

I’m excited about a number of things coming up this year, and I wanted to tell you about some of them.

My 5th Microsoft MVP Award

Yesterday morning I learned that I received my fifth Microsoft MVP award. As it is each time, it’s an incredible honor to be put in the company of such talented people. The MVP program lets me spend time with some of the brightest and most motivated SharePoint / Office365 people on the planet.

Sympraxis Consulting LLC

Sympraxis LogoMany of you who know me may not be familiar with Sympraxis Consulting LLC. It’s my own little company that I started when I went out on my own (sort of; see below). 2015 promises to be a transition year for my little company. (One resolution I should probably make is to come up with a better Web site than the WSS3-based one I’ve had limping along for the last six years!) Back in 2008, my buddy Pete Sterpe (@petesterpe) and I started Sympraxis together with big dreams. The Fall of 2008 seemed like such a great time – not. Sadly, due as much to the economy as anything else, Pete realized about a year in that he needed a more solid paycheck to fit his life goals at the time.

Luckily for me, Pete is rejoining me at Sympraxis. I’ve known Pete since 1996, when we worked together at Renaissance Solutions. Renaissance focused on knowledge management and performance enhancement by utilizing technology and the Balanced Scorecard. You may know better now where some of my rhetoric comes from. (Sadly even the Way Back Machine doesn’t have a good snapshot of Renaissance from those times, though it does have one of the successor company, Renaissance Worldwide.)

Pete will be ramping back up with Sympraxis as his existing work ramps down, and I am delighted to have him back. He’s one of the sharpest people I’ve ever worked with and our business ethics are perfectly attuned. I hope you get a chance to meet Pete in the near future. You can check out his blog to get to know him a little bit. Since he never changed his About page, you can read how he started Sympraxis with me!

Partnerships

I’ve got two nascent partnerships I’m working on that I’m very excited about. I’ve written about them before but I wanted to go over them here again.

Seven Sigma / Glyma

Seven SigmaThe first relationship is with the folks at Seven Sigma down in Perth Australia. Paul Culmsee (@paulculmsee) and Chris Tomich (@christomich82) are two of the smartest folks I know in SharePoint land. It turns out that we’ve been admiring each other from afar for a long time. If they weren’t all the way around the planet in Perth, I’m sure we would have worked together sooner. I was lucky enough to meet both of them when I was down in Australia at ShareThePoint‘s 5th Annual Australian SharePoint Conference in Sydney last July. (It’s a great conference if you are anywhere near there for the next one.) We talked about the fact that it would be great to work together in some way and we’re still trying to figure out exactly how that might work. It will be something we’re both convinced will add value and as the partnership starts to gel I think it’s going to be an exciting thing to work together.

Their Glyma product really gets the knowledge management part of me excited. Using the concept of dialog mapping, it’s a fantastic way to encapsulate and map the knowledge contained within an organization as well as a way to help map strategic focus and direction decisions. Watch for more about Glyma from me in the weeks and months ahead.

Dynamic Owl / Bonzai Intranets

DynamicOwlLogoThe second relationship is with my friends at Dynamic Owl in Vancouver, BC, Canada. Dynamic Owl is headed by Michal Pisarek (@michalpisarek) and he has a small group of incredibly intelligent folks working with him. Michal and I have talked about ways we could work together over the years, but have never come up with something that makes sense.

Bonzai IntranetThe Owls’ product is called Bonzai Intranet and I’m incredibly impressed with what Matthew Carriere (@matthewcarriere) and Shereen Qumsieh (@msshushu) have built in a very short time. They’ve taken the learning that they have over the years working in SharePoint and built some of the most common things that they’ve seen time and time again in customer Intranets. The most impressive thing about it to me is the architecture. The majority of the functionality is driven from the client side using AngularJS and calls to CSOM and REST. I’ve been working with them to think through how their architecture might work with Office 365. As we all know there are some different challenges there, but with a bit of good thinking ahead of time I think they are going to be able to do some amazing things.

I’m not exactly sure where these two relationships will lead, but I’m hoping it will go far beyond just pasting each others’ logos into our Web sites. These are great people with whom I hope to work a lot more in 2015.

Community

SharePoint – and by extension – Office365 – would never be what they are without the incredibly strong community around them.

IT Unity Webinar: #CollabTalk, The Show

ITUnityLogoI’m joining an impressive crew of people to do a new video series on IT Unity. Many of you have probably participated in the #CollabTalk tweet jams that have been going on for the last couple of years. Tweet jams are great, but of course they only have a certain utility since we can type just 140 characters at a time. With this new video series hosted by IT Unity, Christian Buckley (@buckleyplanet), Naomi Moneypenny (@nmoneypenny), Benjamin Niaulin (@bniaulin), and I will be able to go into much more depth about topics that we think are important to people who are interested in Office365. I think we will have a lot of fun and talk about some really important topics at a level of depth that we could never do in a tweet jam.

CollabTalk - Tiny - Tiny

Conferences

I love speaking at conferences. I learn so much talking about what I do with attendees and getting to go to other speakers’ sessions is the icing on the cake. I used to always say I’d like to teach some day, and this is my way of doing a bit of it on a regular basis.

In 2014 I was fortunate to speak at ShareThePoint’s conferences in Sydney and Auckland, which was my first chance to visit that side of the world. We made it into a family trip to Vietnam and Cambodia, so it was quite the globe-trotting romp. (Don’t look at a globe and tell me how ridiculous that was; I know.)

There were lots of other great conferences, too: SEF in Stockholm, Sweden; SPTechCon in San Francisco and Boston; and SharePointFest in Chicago, just to name some of the most prominent ones.

This year I already have SPTechCon in Austin, TX lined up, along with SharePoint Evolution in London. If you’re dying to keep up with where I’ll be, watch the Speaking page here.

Oh, and Clients!

I’ve been very lucky to have some wonderful clients who have engaged me multiple times over the years. As is always my hope, with most of them I have a long-standing, open and honest relationship. Along with all the fun stuff above, I do occasionally focus on earning a living, and my clients are the best. Here’s to a lot of great projects in 2015!

Summary

blackshadesYeah, it may be true. The future may be so bright I’ve gotta wear shades. I don’t mean this in a gloating way by any means. I’m incredibly lucky to be in the position I’m in at this point in my career. For many reasons which I won’t go into here, my time in the sun seems to be in my 50s. Many of my contemporaries may be able to rest on their laurels at this age, having accomplished their world-changing stuff in their 20s or 30s. I’m excited to know that my time is now or may be yet to come. I can’t wait to see what else 2015 has in store for me. Happy New Year!

Don’t Use a Query String Parameter Called ID Unless You Mean the Item ID

The other day I got a question from my pal D’arce Hess (@DarceHess):

I am using jsLink on a couple lists and I have an interesting circumstance I’m running into.

Scenario: I have a list of Work Centers and each work center has associated machines that are in another list.

I’m having an interesting situation that when I click on the link in the Work Center, it is supposed to reload the same page and append the Work Center ID to the url  so that it will load the associated machines in the other list. I have the functionality working, however for some reason, when it adds the ID and reloads the page, it is changing the page layout from the layout that is chosen for the initial .aspx page.

Since it is literally re-loading the same page, just with an additional ID, I’m not creating new pages. Any ideas of what may be causing this?

After some back and forth about it, I realized that D’arce was using a query string parameter named “ID”. (I know, it should have been obvious to me right away, but we have a way of using shorthand when we describe technical issues that always makes a little back and forth useful.)

ID seems to be very reserved in SharePoint. Someone probably left some sort of back door thing in SharePoint once a long time ago, because I’ve seen using the ID parameter on the query string for anything other than the item ID cause issues way back to SharePoint 2007 at least.

By switching from ID to WorkCenter for the parameter name, all was right in the world again. For example, instead of “ID=1″, “WorkCenter=1″. Not only does this fix the issue, you end up with a query string parameter name that is more descriptive. That’s useful down the road for maintenance and will even make more sense to users. “That URL is ugly” may become “Oh, I’m selecting the WorkCenter”.