Building Your Own Micro-Service APIs to Wrap Office 365 or SharePoint 2013 for JavaScript Web Developers

Office 365 and SharePoint provide a variety of APIs that can be accessed and called from JavaScript.  Imagine the following scenario:

image

Microsoft provides a collection of APIs that you can use to fetch data from SharePoint.  These APIs work quite well but are not exactly intuitive to the non-SharePoint developer (e.g. a web developer who lives in JavaScript/AngularJS/Bootstrap/HTML5 all day). 

Imagine that we have a mobile friendly, responsive web application and we want to display the latest news from SharePoint.  Using JavaScript/AngularJS/HTML5 we can build a nice responsive page layout that has a panel that might look something like this:

image3

If I’m writing an AngularJS controller, what I really want is a JSON object that represents the content to be rendered.  The SharePoint API can provide this to me using the search APIs which will provide the content through either REST or JavaScript APIs.  However, there are some SharePoint specific “idiosyncrasies” (kind word for it!) that take some learning to master these APIs.  These include:

  • Understanding all the built in search fields, content types, etc. and their non-intuitive identifiers (for example, did you know that “News” has a content type ID of “ǂǂ416e6e6f756e63656d656e74”?)

  • With the search APIs, you have to ask for fields to be returned such as the body text of the news item. 
  • With search, you can be returned multiple result sets – for example, SharePoint will provide one result set of found pages and another of relevant results.

  • Searching, filtering, and sorting all have APIs that need to be learned in order to retrieve the results required.

This is just scratching the surface – you could spend months figuring out the SharePoint search APIs work, and that’s just for fetching content.  Adding content also has its own learning curve as well.

If you jam all this logic into your JavaScript, you’re putting a lot of complexity into your web developer’s hands that could be insulated away. 

A Proposed Approach: Use a Custom Web API to build a Micro-Service

What if instead of using JavaScript to interact with the API, we built a custom web API to act as an abstracted micro-service?  In this scenario, what our poor web developer wants is something as simple as this:

var responsePromise = $http.get(vm.NewsLatestURL, config, {});
     responsePromise.success(function (dataFromServer, status, headers, config) {
         vm.newsItems = dataFromServer;
     });
     responsePromise.error(function (data, status, headers, config) {
         alert(“Loading NewLatest failed!”);
     });

I ask for a JSON object, and I get one returned.  Simple.  Once I had this micro-service written, I could hook up the JavaScript in about 30 seconds.  More importantly, I didn’t need to know anything about SharePoint at all.

How do we build such an API – we can use ASP.NET Web API as our framework.  In this scenario, I built a custom SharePointController that calls a business component that does all the idiosyncratic SharePoint API work and returns a very simple pre-processed JSON object.

image2

The code for the ASP.NET WEB API controller is very simple because all the processing logic is in a separate service class.

public class SharePointController : ApiController
     {
         [Route(“NewsLatest”)]
         public IEnumerable<SharePointNewsModel> GetLatestNews()
         {
             SharePointNewsService service = new SharePointNewsService(URL, UserName, Password);
             return service.LatestNews();
         }

    }

Everything is mediated through a custom developed API – this makes it ridiculous easy to allow web developers to focus on HTML, JavaScript and CSS instead of needing to trace through the SharePoint APIs.

Additional Advantages to this Approach

There are some additional advantages to this approach vs. going straight at the APIs:

  • Microsoft has a tendency to change their APIs, to add new ones or to move them around.  Using a custom API that you control allows you to insulate and centralize the APIs.

  • Using a custom API opens up the possibility of remapping of security identifies or using a service account type approach instead of always assuming the user is a SharePoint user that has logged into Office 365.
  • If you start with SharePoint on-premise and the move to Office 365, this approach will insulate your code from the migration.
  • You can add all sorts of business logic that is useful and interesting before sending the results back to the page.  For example, you could filter the results, limit the results, reformat the HTML, add additional lookup data, etc.  which all sits within your centralized API.
  • If you decide to dump SharePoint and replace it with something else, you’ve isolated it from your JavaScript.
  • You could introduce performance enhancing caching approaches such as storing results in memory or pre-rendering in order to make fetching the data much faster.  Even logging into Office 365 for example takes a couple seconds so having some method to cache content is going to be important for a high volume or high performance web application.

These are in addition to making your web developers lives simpler and allowing them to treat SharePoint as a content repository instead of understanding the guys of the entire platform.