Abbiamo già accennato alle novità proposte da SharePoint 2013 per quanto riguarda l'interfaccia REST, introducendo il modello di programmazione che abbiamo a disposizione durante lo sviluppo di App.
Cerchiamo però di entrare un pò meglio in questo argomento, perchè vi assicuro che ne vale veramente la pena.
Vi ricordate il Client Object Model introdotto un pò di anni fa con SharePoint 2010?
Ecco, fate conto che su SharePoint 2013 è stato innanzitutto notevolmente arricchito (ma questo ormai ve l'ho detto già un pò di volte) e, soprattutto, che il relativo servizio WCF che veniva chiamato ogni volta che si eseguiva il metodo ExecuteQuery (o ExecuteQueryAsync nel caso di script javascript o RIA Silverlight) è stato esposto attraverso una specifica URL e modificato in modo tale da seguire tutte le regole date dalle architetture di tipo REST, dal protocollo OData (utile alla rappresentazione delle varie entità in gioco) e dal protocollo OAuth (utile invece allautenticazione).
Che significa?
Significa che ora abbiamo la possibilità di effettuare delle query HTTP verso un server SharePoint 2013, potendo recuperare non solo i contenuti di liste (così come potevamo già fare nella precedente versione del prodotto, utilizzando il servizio listdata.svc), ma potendo leggere la maggior parte delle informazioni che il Client Object Model stesso espone, assieme alla possibilità di sfruttarne la maggior parte delle funzionalità.
Quindi non abbiamo più a che fare con un semplice servizio per effettuare le normali operazioni CRUD sulle liste SharePoint, ma con una vera e propria interfaccia utile a manipolare dati, eseguire azioni, modificare configurazioni, ecc.. interfaccia che rende disponibili tutte queste funzionalità non solo ad applicazioni SharePoint, ma a qualsiasi client in grado di fare una semplice richiesta HTTP, senza portarsi dietro alcun tipo di riferimento alle librerie di SharePoint.
Per chi di voi non conosce REST, è molto importante capire che REST non è un protocollo, ne un particolare design pattern, ne tanto meno un servizio che ritorna dei dati in JSON o che può permetterci di fare chiamate passando gli ID all'interno delle URL senza usare le querystring. REST è uno stile architetturale orientato alle risorse, in grado di permetterci di costruire applicazioni distribuite basate sul protcollo HTTP e in grado di connettere tra loro piattaforme differenti. I servizi basati su REST espongono una o più azioni (sfruttando sia i metodi GET e POST del protocollo HTTP, sia i verbi PUT, DELETE, ecc..) volte alla gestione di una o più risorse, con un particolare stato, che possono essere recuperate o manipolate tramite specifici identificatori.
Per poter utilizzare le funzionalità REST esposte da SharePoint 2013 dobbiamo prima avvalerci di alcuni prerequisiti:
- Conoscenza dellendpoint e del tipo di operazione da effettuare
- Conoscenza delle entità OData ritornate dalle chiamate ai vari endpoint o da passare in input agli endpoint stessi
- Conoscenza della sintassi da utilizzare per effettuare le varie richieste
- Presenza di un contesto di autenticazione valido (perchè ovviamente ogni azione a seguito di una chiamata ad un endpoint REST di SharePoint 2013, viene eseguita con le credenziali correnti)
Gli endpoint di partenza
Conoscere la URL da chiamare è sicuramente la prima cosa di cui preoccuparsi. SharePoint 2013 espone i suoi endpoint REST attraverso la URL di base:
http://[siteurl]/_api
lasciando perdere il servizio "listdata.svc" (che resta disponibile per retro-compatibilità) e seguendo sicuramente le mode del momento per quanto riguarda la scelta della chiave "api" :)
Detto questo, trovate di seguito gli endpoint esposti dalla preview di SharePoint 2013 da cui partire per effettuare le nostre operazioni client-side:
- http://[siteurl]/_api/site (endpoint di partenza per le funzionalità legate alla site collection)
- http://[siteurl]/_api/web (endpoint di partenza per le funzionalità legate al singolo sito)
- http://[siteurl]/_api/search (endpoint di partenza per le funzionalità di ricerca)
- http://[siteurl]/_api/publishing (endpoint di partenza per le funzionalità di publishing)
- http://[siteurl]/_api/SP.UserProfiles.PeopleManager (endpoint di partenza per le funzionalità legate allo User Profile Service)
Come vedete quindi, già da questi "entry-point", si intravedono un sacco di novità.
Rispetto a prima, possiamo accedere a siti e site collection, possiamo fare ricerche, recuperare informazioni sugli utenti dallo User Profile Service ed utilizzare le funzionalità di Publishing, il tutto utilizzando delle richieste HTTP. Il che è veramente fantastico!
La sintassi
Per sfruttare le funzionalità esposte da ciascun endpoint, dobbiamo però conoscere la sintassi da utilizzare per comporre la nostra URL utile poi alla chiamata HTTP verso il server SharePoint 2013. All'interno della documentazione c'è un fantastico diagramma che spiega a grandi linee le regole sintattiche di composizione della URL, ve la riporto qua.
Come potete vedere abbiamo sia la possibilità di utilizzare tutti gli operatori definiti dal protocollo OData per filtrare, selezionare, paginare, ecc.. sia la possibilità di richiamare specifiche classi, metodi o proprietà definite dalle strutture proprie delle librerie del Client Object Model di SharePoint 2013.
Giusto per farvi capire, all'endpoint:
http://[siteurl]/_api/web
corrisponde la classe "Web" del namespace "Microsoft.SharePoint.Client", il che significa che per esempio potete recuperare il nome di un particolare sito SharePoint tramite una richiesta HTTP alla seguente URL:
http://[siteurl]/_api/web/title
Con questa URL stiamo semplicemente richiedendo il valore della proprietà "Title" della classe "Web" propria del Client Object Model di SharePoint 2013.
Riguardo il formato dei dati invece, sappiate che potete utilizzare sia JSON che XML. Se utilizzate l'URL che abbiamo appena visto all'interno del vostro browser, vi ritornerà XML. Ma potete cambiare questa cosa modificando i parametri della vostra richiesta HTTP.
Nei prossimi post vedremo nel dettaglio alcuni esempi, così da capire bene queste regole.
Intanto vi lascio un pò di documentazione:
- http://msdn.microsoft.com/en-us/library/fp142385(v=office.15)
