When building your application, should you use REST or an SDK? The choice seems almost religious but often one makes more sense than the other.

Gone are the days when we were building self-contained applications. Nowadays, they are typically thin clients connecting to data stored elsewhere. This is especially the case for applications for Office 365. There is abundance of data stored in Office 365. All you need to do is to reach out, and there are two common ways of doing it.

Connect to the Microsoft cloud using REST

With a few exceptions, all services in the Microsoft cloud offer a REST API for applications to communicate with them and interact with their data. Using REST is simple and comes down to composing a request with the correct URL, headers and optionally a body.

No matter if you’re using JavaScript, C#, Python or golang: if you can issue a web request, you can communicate with the Microsoft cloud.

Connect to the Microsoft cloud using an SDK

Another way of communicating with services in the Microsoft cloud is by using an SDK. SDK is an abstraction later on top of the web API exposed by the particular service. Typically it abstracts away complexities such as authentication allowing you to focus on your work.

SDK is built for a specific stack which has its pros and cons. Well get to them in a minute.

SDK vs REST on the Microsoft Cloud

So with the two options available, which one should you use? Many developers swear by one or the other. Theoretically, both methods have their strengths and advantages. But in practice one of them makes more sense. Have a look for yourself.

It’s just text

REST requests are web requests to a specific URL with a set of headers and sometimes a body. But the URL is just a piece of text that can quickly get complex the moment you start using OData or similar kinds of expressions. It’s easy to make a typo or incorrectly escape an argument. Typo in a string is not a compiler error and you won’t know about it until you run your code. You could catch it with a unit test, unless you copied the URL from the code to the test along with the typo.

Using an SDK means writing code. SDK has types guiding you to use the right types of attributes, intellisense to help you be more efficient and any typo, unless in resource’s name, will be caught by the compiler.

It’s verbose and it’s good and bad

You could think of REST as a low-level API for the web. There is nothing between you and the service and you need to tell it exactly what you want it to do.

On one hand it’s a good thing. Lack of abstraction helps you to understand how the API works and when things break you get the raw response from the API which could contain some details that could help you find out what’s wrong.

But the verbosity has its price. The moment you start using more complex capabilities such as batching requests or properly handling throttling or even authentication, it will take significant effort to get everything right. A good SDK, does all of this, and more, for you, allowing you to focus on the job.

Not so cutting edge

Different product teams take different approach to releasing their SDKs. Some autogenerate them from the API, some build it manually thinking about scenarios that developers want to achieve. No matter the approach, it could be that the API you want to use is not yet available in the SDK. In such case you can postpone building the functionality, which rarely is a viable option, revert to using REST or build your own wrapper that you’ll replace after the SDK has been updated. SDKs are a point-in-time representation of the corresponding API. When things change in the API, you need a new SDK.

None of this is an issue when using REST. If the API is exposed, you can call it. It’s that simple.

But I’m coding in X

SDKs are built for the particular technology stack. Taking SharePoint as an example, there is an official SDK for .Net, and community-driven SDK for JavaScript. If these languages are your development stack, you’re in good hands. But if you’re building things in .net core, golang, Python or native iOS apps, you’re out of luck and will either need to defer to using REST or build your own SDK.

When you’re used to working with REST, you can more easily switch between the different technology stacks. As long as you know how to issue a web request on the particular stack, you will be good to go and you will be able to benefit of your existing experience.

On a related note, if you switch between different technology stacks, you might prefer to use REST. SDKs often strive to fit paradigms of the particular stack, but there might be implementation nuances between the different stacks that could end up confusing you. REST on the other hand, is just REST no matter if you’re coding for iOS or in C#.

Some examples

Theory aside, let’s have a look at a few examples that could justify using one approach over the other.

You build SharePoint solutions for organizations on the Microsoft stack, and that’s it

In your job, you and your colleagues almost exclusively focus on building solutions that integrate with SharePoint. Your customers are organizations with significant investments in Microsoft technology. In the past, you would typically build Farm solutions and communicate with SharePoint using the server-side object model. Nowadays, you use SharePoint Framework to build the UI and remote code for things like long-running operations or provisioning.

With such specific focus, you would get the most benefit from using the PnP Core Component (or PnP CSOM as some refer to it) for managed code and PnPjs for client-side communication with SharePoint. The PnP Core Component offers you a lot of convenience methods for remotely communicating with SharePoint. Using the fluent API of PnPjs you will be able to more easily communicate with SharePoint and use complex features such as request batching without pulling your hair out.

You build solutions for Office 365 that also include some Azure workloads

Your customers are in the cloud and you build for them productivity solutions that combine the information from the different Office 365 services. Processing and maybe even storage of some of the data is offloaded to Azure. Your solutions are built on the Microsoft stack.

Microsoft Graph does a great job bringing together information from the different services in Office 365. For SharePoint scenarios that go beyond accessing files or sites, you need to use SharePoint APIs. To communicate with both APIs, using the SDK will give you the best experience and efficiency. Depending on which services in Azure you’re using exactly, there should be a .NET SDK available for it. In some cases the latest capabilities are not available in the SDK so if you need to use them, you would need to defer to using REST.

You’re an ISV and you build a SaaS solution that integrates with Office 365

Being an ISV you pick a cloud-native stack that can support your SaaS solution. You go either with Docker containers or fully serverless, most likely on a Linux runtime.

For communicating with Office 365, you can use one of the different Microsoft Graph SDKs available for the most popular development platforms. For interacting with SharePoint the available options vary. If you built your solution on Node.js, you can use the community-driven PnPjs SDK. If you’re using .net core or other stack, you’re out of luck as at this moment there are no SDKs available and you would need to use REST.

You’re building different solutions on different platforms

Your organization builds a variety of solutions that range from SharePoint Framework web parts to mobile apps for iOS and Android and everything in between. You and your colleagues have a broad skillset and regularly switch between the type of applications that your organization is building.

Each SDK comes with its own way of communicating with the server-side API. To prevent yourself from having to fully understand the intricacies of each and every SDK on each and every platform and increase the reusability of your code, you will likely get more benefit from using REST than the different SDKs.

Rule of thumb

If you focus on working with a specific technology stack, you should default to using the dedicated SDK. It will help you to work effectively and avoid trivial, yet hard to spot, errors. If you’re typically experimenting with different technologies or build solutions that span multiple services and you want to reuse code across all of them, REST might be more beneficial to you.

Photo by Markus Spiske on Unsplash