A Brief Overview of the OneDrive RESTful API

  • Article

Editor’s note: The following post was written by .NET MVP Troy Garner as part of our Technical Tuesday series.

The phrase “The Cloud” is usually regarded as a mystery to many at first, yet with the increasing demand of having information synchronized across various devices and platforms, services like OneDrive have been increasingly recognized as popular solutions for centralized data storage. Whether you know how the cloud works or not, the inner-workings of the cloud are usually not discussed in too much detail because implementation can vary – and this might be why it is such a big mystery to some. The phrase itself only has a general definition.

Recently, Microsoft released the OneDrive REST API which provides developers with a flexible and scalable interface to interact with their cloud-based hosting service, and this means bigger and better opportunities for data manipulation across virtually any platform, with little to no headaches.

What is REST?
Although this article is not specifically about REST, I believe it is important to have an abstract understanding of the fundamentals of REST to become familiar with what the OneDrive API is all about.
“REST” is an acronym related to an architectural design principle, which stands for “Representational State Transfer.” It’s implemented within a stateless, client-server, cacheable communications protocol – which in most cases is HTTP. The behavior of the “RESTful” design is geared towards networked applications with the idea that HTTP can sort of “mask off” the complexities of other alternative mechanisms to make calls between machines.

Benefits of the OneDrive REST API?
A few advantages of REST is that it is very fully-featured, lightweight, and easy to use. Of course, I am not here to talk to you entirely about what REST is and why it is used, but rather, explain why this promotes great opportunities for OneDrive integration. Here are a few good points to get you started:

1. Because this API is “RESTful” you are not limited to any specific platform or language of choice, as long as you have the ability to communicate with the API over HTTP.
2. The API provides a secure authentication layer (OAuth 2.0), and by default, all resources will be returned with secure HTTPS URLs.
3. Permissions are “scoped” and user consent is requested before access is granted to any portion of OneDrive through the REST API.
4. JSON is used for the HTTP requests and responses, which is nice because JSON is a very minimalistic data structure, and this helps especially when lightening the load of incoming and outgoing requests over a network.
5. Throttling limits for OneDrive requests ensure that the experience for others is not degraded, but the response of exceeding the limit provides a convenient “Retry-After” header which specifies when the rejected requests timeout period will expire. (Note: As a developer, you’ll know that you’ve exceeded the limit if you receive a 429 HTTP response code, which indicates “Too Many Requests.)
6. All of the most common HTTP verbs are supported (GET, POST, PUT, DELETE, MOVE, COPY), and in cases where a verb is blocked, or cannot be used for some reason, verb tunneling through a POST request can still be used to allow a specific verb to be used.
7. Large file upload support (up to 10GB - chunked upload), upload from URL, CORS support, resumable downloads, and more…
Additionally, samples are already freely available for JavaScript, iOS, and Android developers so that non-Windows developers (and web developers) can feel at home if they want to take advantage of the large set of features the OneDrive API provides.

An example response for retrieving the default drive is shown below: 
 
Feature Overview
A few features of the OneDrive REST API include the ability to:
1. Download and upload files
2. Get user data
3. Obtain user consent
4. View file and folder properties
5. Move, copy, create, or delete files and folders
6. Create, update, read, or delete albums
7. Read, create, or delete tags

Conclusion
With all these features embedded within the powerful OneDrive REST API, the purpose of the API itself is only limited to one’s imagination. Just make sure to read the OneDrive API Terms and Conditions as well as the Branding Guidelines if you choose to incorporate OneDrive into your apps. I wouldn’t consider this API to be very small, therefore a good starting point would be to take a look at this page here on Developing with the OneDrive API.

There are a few things to consider before deciding the that OneDrive API is the right candidate for you to be using as a developer, just like any other possible candidate involved when considering your application design. Microsoft makes a note that although OneDrive stores OneNote notebooks, it is not recommended to be using the OneDrive API to work with OneNote notebooks – instead, they suggest that you use the OneNote API, but that is out of this articles scope unfortunately so I won’t go into detail on that one.
One of the best features about the OneDrive REST API, for me, is the ability to resume downloads by using the HTTP Range header to specify the range of the bytes not yet downloaded. I don’t know how many times I’ve used other services and had a download interrupted by an unreliable network or some other factor.

Nonetheless, good luck! I hope that there are people out there who will start to consider OneDrive as their preferred cloud-based file storage service after witnessing the power of these APIs firsthand!

About the author
Troy Garner is a technical evangelist, as well as an aspiring programmer with a keen interest in developer security, reverse engineering, crash dump analysis, and other similar topics. Since first learning about computers through an old Windows 95 machine, he hopes to contribute to the technical world in a positive way while learning new things and sharing his knowledge with others, and has been re-awarded as a Microsoft MVP for 2015 as a .NET Programmer for the 4th consecutive year from the first award in 2012 for Visual Basic.