App Designs in SharePoint 2013

copyright from: www.shillier.com

3/18/2013 Update: After presenting this material at a few user groups, I decided this article needs a better structure to present the ideas. So I have updated the table to reflect more nuance than just "good" and "bad". I'm interested in feedback as I am using this as a cornerstone for many presentations. Catch me on Twitter @ScotHillier.

The SharePoint 2013 app model supports three hosting models and two client APIs. This means that there are 12 permutations of app design as shown in the table below. In this post, I’ll briefly explain when you should use each app design.

Key

Excellent Choice

SharePoint-Hosted App, JavaScript, REST

SharePoint-Hosted apps must use JavaScript and can use either REST or CSOM (aka, JSOM). However, REST is by far the preferred approach. Why? Bringing the SharePoint context to the client is a uniquely-SharePoint idea that no other technology uses. REST is a standard that many technologies understand. Your code is a lot more “standard” when you use REST. Furthermore, key libraries such as jQuery already support REST.

Cloud-Hosted apps, C#, CSOM

Cloud-hosted apps (meaning both provider-hosted and autohosted) can use JavaScript/REST, C#/REST, or C#/CSOM. Again, some combinations are better than others.

When working with cloud-hosted apps, you often have to work with OAuth tokens. The TokenHelper class, which is included in Visual Studio makes this much easier. So, immediately you can see that C# is a better choice than JavaScript where tokens are important. JavaScript does have a role to play, but it is primarily when you need to use the cross-domain library to overcome firewall limitations.

Once you have concluded that C# is the way to go, you’ll discover that writing CSOM code is much easier than REST. CSOM can be used synchronously in the managed object model, which makes the code very simple and straightforward. REST calls, on the other hand, have some serious drawbacks. First, they require async round trips to the server to acquire the FormDigest from SharePoint. Second, you have to create POST messages by hand in code, which is ugly.

Cross-Domain Support

Cloud-Hosted, JavaScript, CSOM

JavaScript/CSOM (aka JSOM) requires a SharePoint context. In classic JSOM, the context is created in code within a page that is hosted in SharePoint. When you consider that cloud-hosted apps never run pages that have such a context, it is clear to see that classic JSOM can't work in remote webs.

SharePoint 2013, however,provides a workaround utilizing the SP.ProxyWebRequestExecutorFactory that allows you to make cross-domain calls using JSOM. These cross-domain calls are in lieu of using C#, CSOM, and the OAuth plumbing, which is a better choice but may not be possible in all situations. If, for example, you have a remote web that is outside the firewall and needs to call back to an on-premise SharePoint farm, OAuth will not work. In this case, the cross-domain JSOM solves the problem.

Cloud-Hosted, JavaScript, REST

There is also a REST version of the cross-domain library, which accomplishes the same ends. Again, REST is more standard than JSOM, so you should favor this approach.

 Impossible

C# cannot be used in a SharePoint-hosted app in any way because server-side code is not allowed. Period. There is no way around this fact.

 Debate Over Beers

SharePoint-Hosted App, JavaScript, JSOM

I've already made the argument that REST is more of a standard than JSOM. However, there are legitimate advantages to using JSOM over REST. The most-important advantage is that JSOM is currently a superset of REST functionality. There are some operations that can't be performed in REST. For example, updating content types and pushing changes to all lists is simple in JSOM, but not supported in REST as far as I can tell (even though the API sort of suggests it is).

The second advanatge of JSOM is that it currently has much better documentation than the REST API. This is because it has been around since 2010. I'm sure the REST documentation will catch up, but right now, it is often frustrating to do anything beyond CRUD operations.

Finally, JSOM payloads are smaller than REST payloads. Some non-scientific Fiddler analysis has shown REST payloads to be as much as 2x JSOM payloads.

Cloud-Hosted, C#, REST

I've already gone over some of the reasons why I think this combination is not a winner. I've listed it here because it is possible so someone may want to debate its merits. However, I think this is pattern is so tedious that I would never use it.

Conclusions

A couple of clear takeaways from this analysis:

·        If you are writing a SharePoint-Hosted app, use JavaScript and the REST API, not JSOM
    unless you are involved with operations not currently supported by REST

·        If you are writing cloud-hosted apps, use C# and the managed version of CSOM, not REST

·        If you are writing a cloud-hosted app and you are trying to call back into an on-premises
    SharePoint farm through a firewall, use JavaScript, REST, and the cross-domain library.