REST and OData with Office365 APIs

When communicate with Office or SharePoint APIs, its important fact that knowledge on representational transfer protocol and OData protocols while moving with deep customization’s.

what is REST (Representational State Transfer)?

In simple terms REST is all about below;

  • Predefined set of stateless operation which identified by URL
  • Responses may contain HTML, JSON, XML or any other defined format which supported
  • GET, POST, PUT, DELETE are most common forms of HTTP verbs

rest_api

Eg.

GET:
http:///_api/web/lists/GetByTitle('Test')
GET:
https://outlook.office.com/api/v2.0/me/MailFolders/sentitems/messages/

what is OData (Open Data Protocol)?

  • Equipped with query and creational capabilities on REST APIs
  • Initiated by Microsoft in year 2007
  • Format [http or https]://<REST Endpoint URL>/<query>
http://<end point URI>?$select=value&$filter=condition$orderby=value

Open Standardization?
Standards which are developed with the involvement of community (mostly with developers). Open standards inherited to office 365 API development in following manners;
• Most of Office 365 APIs are exposed as a RESTful APIs
• Its implemented with OData 4.0 (as for year 2016)

OData queries?
OData queries is common standard which elaborated above also included in the SharePoint and Office365 end point data querying. Its ultra simple if you know the basics and played with this. Follow the following links and be expert on this.

www.odata.org : Official site for OData

graph.microsoft.io : Explore Microsoft Office365 API with queries

OData validator to validate your REST endpoints

Note : If you noticed there are versions associated with most of cloud based endpoints. Cloud services are continuously pushing changes to its services as sooner changes are ready, so then returned patterns may changed for same query. To avoid custom applications get break due to changed on endpoint, it classifies under version metadata. Simply you can pick any version which satisfies your requirement.

Querying SharePoint Endpoints as below;

SharePoint REST service query option syntax
Courtesy : msdn.microsoft.com

 

Further references 

Clear | Remove | Delete Managed metadata (Taxanomy) column value in SharePoint List/ library

You may find many references to write into taxonomy columns (aka. managed metadata columns) but the clearing those is pretty much tricky.

Following code sample guide you through how you can clear the taxonomy column value in you custom client side application (JSOM) based on SharePoint.

//USAGE:
//clearWithValue =true => for clear saved taxanomy column values
//clearWithValue =false => wite into taxanomy column 

function saveValuesToManagedMetadataColumns(listName, fieldId, taxanomyLabel, siteUrl, clearWithValue) {

    //You many need seperate function to resolve GUID for the lable.
//Its based on your requirement and for now its hardcoded
    var taxonmyGuid = "9f75f519-51f8-4723-9182-7e8225a54031";
//Loading context and list
    var context = new SP.ClientContext(siteUrl);
    var list = context.get_web().get_lists().getByTitle(listName);
    //Getting item to update
    var camlQuery = new SP.CamlQuery();
    camlQuery.set_viewXml("<View>" +
        "<Query>" +
        "<Where><Eq>" +
        "<FieldRef Name=\'ID\'/>" +
        "<Value Type=\'Number\'>" + fieldId + "</Value>" +
        "</Eq></Where>" +
        "</Query>" +
        "</View>");
    var items = list.getItems(camlQuery);
//Load selected items to context
    context.load(items);
    //Loading MMS field
    var field = list.get_fields().getByInternalNameOrTitle("taxanomyColumnName");
    var txField = context.castTo(field, SP.Taxonomy.TaxonomyField);
//Load field to context
    context.load(txField);

    context.executeQueryAsync(function () {
        //getting term set ID
        var functionTermSetId = txField.get_termSetId().toString();
        //Term value build for update..this is not useful is your purpose only for clearing
//But for illustration..got below also to show off
        var termValue = new SP.Taxonomy.TaxonomyFieldValue();
        termValue.set_label(taxanomyLabel);
        termValue.set_termGuid(taxonmyGuid);
        termValue.set_wssId(-1);
//Iterate through collection and update
        var e = items.getEnumerator();
        while (e.moveNext()) {
            var item = e.get_current();

            //Save to taxanomy column
            if (clearWithValue == false)
                txField.setFieldValueByValue(item, termValue);

            //Clering taxanomy column
            if (clearWithValue == true)
                txField.validateSetValue(item, null);

            //Set noraml fields..If you have them too
            item.set_item('Title', metadataCollection.Title);

            item.update();
        }
        context.executeQueryAsync(function (sender, args) {
            console.log('Successfully updated item with ', args, serviceId, false);
        }, function (args) {
            console.log('Error on updating item with taxanomy value', args, serviceId, false);
        });

    }, function (args) {
        console.log('Internal server Error on updating item with taxanomy metadata', args, serviceId, false);
    });

}

References
http://sharepoint.stackexchange.com/questions/47719/how-can-i-set-empty-value-to-taxonomyfield-of-microsoft-sharepoint-client-taxono

Integrate SharePoint Documents with Office Web Apps in Custom Solutions

If you are finding way of integrating Office Web Apps(OWA)with your custom solution which built with SharePoint CSOM/ JSOM or with integration of any client site development. Specially in a scenario where you develop your own “SharePoint display template” following integration points will be useful;

View in office web apps

Following link will work; if your requirement is to open your document in OWA. This can be done with simply appending parameter as below;

<uri to your document>?Web=0

Eg:
http://mydomain.local/sites/OWASite/Documents/TechCentro.docx?Web=0

Edit SharePoint documents in OWA

Following way of integration with the Office Web apps which let you to pick your action is; means that whether your action may be read, edit or your default setting.

<Web absolute URi>_layouts/15/WopiFrame.aspx?sourcedoc=<Relative URi to document>&action=<Your action>

Summary of actions as below;

 

&action=default -> Gets default setting of the documents
&action=view    -> Open office app as a read only
&action=edit    -> Open office app as editable

Eg:

http://mydomain.local/sites/OWASite/_layouts/15/WopiFrame.aspx?sourcedoc=/sites/OWASite/Documents/BestPractices.docx&action=edit

You can be changed the default behavior with following approach
https://technet.microsoft.com/en-us/library/ee837425.aspx?f=255&MSPPError=-2147217396

Building URL to the Office Web Apps

If you thinking about how to build your URL; following illustration may be useful.

var owauri="_spPageContextInfo.webAbsoluteUrl" //absolute URL of the SharePoint site
+"/_layouts/15/WopiFrame.aspx?sourcedoc=" //static phrase
+"/sites/OWASite/Documents/TechCentro.docx" //Relative URL to the document
+"&action=edit //Action parameter

Useful resources

https://technet.microsoft.com/en-us/library/ff431685.aspx

TypeScript for Office Dev | Convert Ts App to Office/SharePoint Add-in

TypeScript is not an alternative for any other programming language, it’s simply for make web developer productive when he is coding. It’s not C# for web, its not JavaScript extension or either its not alternative to JavaScript. Based on programming language design basics its for make source more readable to humans while also make its readable to machines.

Before startup, I would like to make you notice some facts over there. Even you are coding on *.ts file which is also known as ‘Typed Script’ in your script references, you are referencing a JavaScript file (*.js). It means that, behind the scene you are generating a JavaScript means that this is just an interface to your scripts.

<script src=”app.js”></script>

app.ts vs app.js in TypeScript application

What is in TypeScript?

  • Classes
  • Interfaces
  • Generics
  • Overloading

Describing on above purposely omitted since as Microsoft developers or as a developer above concepts and implementations are not new topics for us.

Develop TypeScript Application

You can be created TypeScript application as below, and you will get solution as shows in the above image which compares ts and js files which included.

FileNewProjectTemplatesTypeScript“HTML Application with TypeScript”

After you done with the templating you can develop your HTML application with using TypeScript and by integrating any client side framework like AngularJs, ReactJS or any framework you prefer. But my personal preference is Angular or React since they equipped with strong community and rich framework background.

You will use Unified APIs or more generally saying RESTful APIs to communicate with Office application data and services. If you are developing on SharePoint you may also use JSOM based libraries but the recommended way is keep the decoupled concerns with the RESTful APIs since it gives many advantages (Note: wait for explore advantages of moving towards RESTful services when Office Dev on a post in near future) .

References:

Converting TypeScript Application to Add-in (App)

After you done with TypeScript Application, converting app to Office Add-in is few step process. You can be pick which Office application and then all done. By clicking on “Start” you can test the application.

Convert to Office Add-ins

Note: If you developing SharePoint Add-in you are requires to give SharePoint, you requires to give relevant information to connect with it to host the application. For other application types you requires only Office installed on the machine to host the application.

    

Optimize SharePoint REST API with client side caching | Angular JS

If you working with any REST API and having the requirement of getting too many data from the from the DB or lists (in SharePoint) [GET requests]. You may facing slowness in the App, Web Part or in client side web part.

To overcome above issue with the load, one option would be caching of recurring data while you made all other performance improvement points. Following describes how yo improve performance of SharePoint Online/On-prem application which relies on REST API by using caching and uses Angular JS for client side development.

Note: Out of the box (OOTB) Angular JS having caching implementation on the $http, but in following sample I have used “angular-cache” since it give more features such as access to local storage and session storage.

First you should include following references https://github.com/jmdobry/angular-cache/tree/master/dist and include those it in your project.

Secondly, you should configure the caching options. Either you configure caching globally as below on the Angular app.js

//If need to apply all HTTP requests globally

(function () {
'use strict';

// create app
var app = angular.module('app', [
, 'angular-cache'
]);

// startup code
app.run(['$http', 'CacheFactory', function ($http, CacheFactory) {
//cache configs
$http.defaults.cache = CacheFactory('nylFileData', {
maxAge: 15 * 60 * 1000 // Items added to this cache expire after 15 minutes
, cacheFlushInterval: 60 * 60 * 1000 // This cache will clear itself every hour
, deleteOnExpire: 'aggressive' // Items will be deleted from this cache when they expire
, storageMode: 'localStorage' // This cache will use `localStorage`.
});
}]);

Further configurations http://jmdobry.github.io/angular-cache/#configuration-options

Else you can define configurations per Angular service or may be per request.

(function () {
'use strict';
var serviceId = "myService";

angular
.module('app')
.factory(serviceId, ['$http', '$q', 'CacheFactory', myService]);

function myService($http, $q, CacheFactory) {
// init factory
init();

var service = {
getData: getData

};

return service;

//initialization
function init() {
//Cache initialization
CacheFactory('cacheData', {
maxAge: 15 * 60 * 1000 // Items added to this cache expire after 15 minutes
, cacheFlushInterval: 60 * 60 * 1000 // This cache will clear itself every hour
, deleteOnExpire: 'aggressive' // Items will be deleted from this cache when they expire
, storageMode: 'localStorage' // This cache will use `localStorage`
});
}
}
})();

Finally, you should should bind your cache with the request.

 //get data function
function getData() {
var deferred = $q.defer();
var start = new Date().getTime();

//request
$http({
method: 'GET',
cache: CacheFactory.get('cacheData'),
url: webUrl + '/_api/web/lists/getByTitle(\'My List\')/Items',
headers: {
'Accept': 'application/json;odata=verbose',
'Content-Type': 'application/json;odata=verbose'
}
}).then(function successCallback(data) {
// when the response is available
deferred.resolve(data);
console.log('Time to retrieve data - [' + (new Date().getTime() - start) + 'ms]', data, serviceId, false);
}, function errorCallback(error) {
// or server returns response with an error status.
deferred.reject(error);
});

return deferred.promise;
}