​Nota: Estas APIs están actualmente en fase de Preview y pueden sufrir modificaciones cuando se lance la versión definitiva. Naturalmente, no se recomienda el uso de ninguna de estas APIs en un entorno de producción.
En la Conferencia de SharePoint que tuvo lugar en Las Vegas el pasado mes de Abril, Microsoft presentó muchas novedades para nuestro servidor favorito sobre todo en la versión Online: nuevos formularios para sustituir a InfoPath, Office Graph, novedades en las Apps, versión de SDK para Android, mejoras en la API REST, novedades en NAPA y la aparición de nuevas APIs para Office 365.
Respecto a las nuevas APIS, nos encontraremos con las siguientes:
Exchange Online: Permitir el acceso, añadir y modificar elementos tanto a nivel de Calendarios y de Contactos como enviar y consultar correos electrónicos.
Si damos tanta importancia a estas APIs es porque, desde que se presentó el nuevo modelo de Apps y la Office Store, Microsoft apenas habÃa presentado novedades. Algunas de estas APIs (como por ejemplo la API de Exchange Online) eran continuas reclamaciones que le hacÃamos los desarrolladores para poder implementar aplicaciones interesantes y de calidad en la Office Store utilizando Exchange Online. Además el hecho de que estas APIs puedan ser Cross-Plataform da un motivo más a los clientes para unirse a Office 365, bien en un entorno hibrido, bien en un entorno nube.
Desgranando las API de Exchange Online
La API que se incluyen dentro de Exchange es la que más novedades incorpora y, quizás, de la que más partido se le pueda obtener. Principalmente porque Exchange fue de los primeros productos que se decidió llevar a la nube, con lo cual, la base instalada es bastante amplia.
Mail REST API
La Mail REST API proporciona acceso total a los mensajes de correo electrónico en el buzón de un usuario en Exchange Online. Tenemos los siguientes Endpoints disponibles:
Obtener el e-mail:
Podemos obtener el correo electrónico de dos maneras diferentes. Se puede solicitar un conjunto de mensajes de correo electrónico desde una carpeta, opcionalmente filtro o una ordenación, o puede solicitar una dirección de correo electrónico especÃfica por su propiedad ID.
Obtener los mails de la carpeta Inbox:
GET https:``//outlook.office365.com/ews/odata/Me/Inbox/Messages
Accept: application/json;odata.metadata=full
Obtener un e-mail en particular,para ello tendremos que tener el Identificador del e-mail que queremos consultar:
GET <a href=``"https://outlook.office365.com/EWS/OData/Me/Messages"``><span lang=``"EN-US"``>https://outlook.office365.com/EWS/OData/Me/Messages</span></a>(``' ID del mensaje'``)
Accept: application/json;odata.metadata=full
Otra de las posibilidades de que se dispone es, dado que hace uso del estándar OData versión 4.0, es la de poder realizar filtros, paginación, ordenación y número de elementos a mostrar dentro de la propia petición como por ejemplo:
GET https:``//outlook.office365.com/ews/odata/Me/Inbox/Messages?$orderby=DateTimeReceived&$filter=Importance eq Microsoft.Exchange.Services.OData.Model.Importance'Low'&$select=Subject,Importance,DateTimeReceived&$top=5
Accept: application/json;odata.metadata=full
En el ejemplo propuesto ordenamos los mensajes por fecha de creación haciendo uso de $orderby, filtramos mediante el parámetro $filter por los elementos que son de importancia "Low" y mostramos los siguientes campos: Subject, Importance y DateTimeReceived utilizando $select. Indicamos el número de elementos que nos traemos con la sentencia $top donde en este caso nos trae los primeros 5 elementos.
Nota: El número de elementos que nos podemos traer por petición es de un máximo de 500. Por defecto está limitado a 50, pero se puede incrementar hasta 500.
Crear un e-mail:
Para crear un mail tendremos que crear un objeto JSON Â con la estructura de un e-mail: Mensaje, Cuerpo y Recipientes. El objeto tendrÃa la siguiente estructura:
{
  ``"@odata.type"``:``"#Microsoft.Exchange.Services.OData.Model.Message"``,
  ``"Subject"``:``"Articulo Compartimos para utilizar las nuevas APIS de Office 365"``,
  ``"Importance"``:``"High"``,
  ``"Body"``: {
    ``"ContentType"``:``"HTML"``,
    ``"Content"``:``"Aquà está el articulo leerlo y cualquier cosa me decÃs"
  ``},
  ``"ToRecipients"``: [
    ``{
      ``"Name"``:``"Alberto Diaz"``,
      ``"Address"``:``"adiazcan@compartimoss.com"
    ``},
{
      ``"Name"``:``"JC Gonzalez"``,
      ``"Address"``:``"jcg1981@compartimoss.com"
    ``},{
      ``"Name"``:``"Fabian Imaz"``,
      ``"Address"``:``"Fabian.imaz@compartimoss.com"
    ``},{
      ``"Name"``:``"Gustavo Velez"``,
      ``"Address"``:``"Gustavo.velez@compartimoss.com"
    ``}
  ``]
}
Sobre este objeto realizaremos la siguiente petición:
POST https:``//outlook.office365.com/ews/odata/Me/Drafts/Messages
NOTA: En el momento que creas un e-mail por defecto se crea dentro de la carpeta de borradores (se puede modificar para que directamente se envÃe el mail directamente estableciendo el parámetro "MessageDispostion" al valor "SendAndSaveCopy", el valor por defecto es "SaveOnly").
Actualizar un e-mail:
Una vez tenemos un mensaje en la carpeta de borradores, podemos realizar cualquier modificación del mismo, por un lado, generamos el objeto JSON con los campos a modificar, por ejemplo, vamos a modificar el Cuerpo del mensaje:
{
  ``"Body"``: {
    ``"ContentType"``:``"HTML"``,
    ``"Content"``:``"Vamos a modificar el mensaje!!"
  ``}
}
Con el objeto creado se realiza la siguiente petición:
Se puede eliminar correo electrónico, simplemente enviando una solicitud DELETE para la dirección de la entidad de mensajes como por ejemplo, la siguiente petición.
Con el Calendar API vamos a tener acceso tanto a los grupos del Calendario como los propios elementos, desde la propia API se va a poder contestar a Reuniones o Meetings propuestos.
A continuación vamos a ver algunas de las operaciones disponibles en la API:
Consultar los elementos del calendario: Mediante la propiedad de Events obtenemos los elementos que tenemos en nuestros calendarios. Además, de la misma forma que con el mail, al hacer uso de OData es posible utilizar la propiedad "filter" para filtrar los elementos que se devolverán en la respuesta.
GET https:``//outlook.office365.com/ews/odata/Me/Calendar/Events?$filter=Start le 2014-02-14T05:00:00Z and End ge 2014-02-10T05:00:00Z
Accept: application/json
Actualizar los elementos: Para actualizar un elemento de calendario, hay que realizar una petición PATCH para la URL del evento. En esta petición hay que incluir un objeto JSON con las propiedades para actualizar. Si actualiza una reunión en la que el usuario es el organizador, se envÃa una actualización a todos los asistentes. El ejemplo siguiente actualiza la ubicación de una reunión.
Responder a una petición de reunión: Para responder a una petición hay que realizar varios pasos debido a que una Petición de reunión es un Objeto Mensaje y no un objeto Calendario. Por lo que en primer lugar, tendremos que consultar el mensaje. En dicho mensaje tendremos, por un lado en la propiedad "MeetingMessageType" y, en la siguiente propiedad, tendremos un EventID que es el Identificador de la solicitud (posteriormente lo utilizaremos para contestar a dicha solicitud).
Una vez hemos consultado el mensaje y tenemos la información relativa al EVENTID podemos enviar una contestación a dicha convocatoria. Como por ejemplo:
POST https:``//outlook.office365.com/ews/odata/Me/Events('Identificador')/Accept?MessageDisposition=SendAndSaveCopy
Con la Contact REST API puedes consultar, añadir, modificar y eliminar cualquier contacto.
Consultar los Contactos:
Para obtener contactos, enviar una petición GET a la propiedad contactos de la carpeta de contactos. Dentro de la petición se puede utilizar el parámetro "Select" para indicar las propiedades que queremos que se devuelvan en la respuesta.
GET https:``//outlook.office365.com/ews/odata/Me/Contacts?$select=DisplayName,EmailAddress1,Birthday,Categories
Accept: application/json
Crear un Contacto:
Para añadir un contacto, hay que enviar una solicitud POST en la que se envÃa un objeto JSON indicando que ese objeto es de tipo Contacto más la representación del contacto.
POST https:``//outlook.office365.com/ews/odata/Me/Contacts
  ``"@odata.type"``:``"#Microsoft.Exchange.Services.OData.Model.Contact"``,
  ``"GivenName"``:``"Santiago "``,
  ``"Surname"``:``"Porras"``,
  ``"EmailAddress1"``:``"s.porras@mvp.microsoft.com"
}
Actualizar un Contacto:
Para modificar un contacto hay que enviar una solicitud "PATCH" hacia la dirección del contacto y se adjunta un objeto JSON con las propiedades que queremos modificar.
Una vez tenemos instalada las Office 365 API Tools, abrimos Visual Studio y creamos un proyecto ASP. NET MVC 4 seleccionando la plantilla WebAPI. A continuación, a nuestro proyecto le vamos a añadir la conexión a los servicios REST de la API de Office 365. Para añadirlos, nos dirigimos al Explorador de soluciones, Agregar Servicio conectado tal y como se muestra en la siguiente imagen:
Aparecerá el Administrador de servicios. Seleccionamos Office365 e introducimos los datos de usuario y contraseña de la cuenta de Office 365 que se vaya a utilizar. Una vez autentificado contra el Tenant de Office365, veremos una lista de tres servicios: Active Directory, Exchange y SharePoint. Inicialmente, la columna Permisos a la derecha de cada servicio estará vacÃa. En nuestro ejemplo vamos a seleccionar Exchange. Una vez seleccionado pulsamos Aceptar (Imagen 2).
Dado que no están establecidos los permisos, al tratarse de una versión preview, estos se solicitan por pantalla. En nuestro caso, vamos a otorgar todos los permisos para poder ver todas las opciones que vienen incluidas y que hemos visto en este artÃculo.
Una vez hemos añadido la API a nuestro proyecto revisamos la estructura de nuestro proyecto que quedará de la siguiente forma:
Tal y como hemos remarcado en la imagen, se han añadido dos controladores (ExchangeSampleController, Office365CommonController), un modelo (Office365ServiceInfo) y una serie de vistas para poder comprobar las capacidades de estas APIs.
Si analizamos los ficheros que se han añadido:
Office365ServiceInfo: En esta clase disponemos del modelo que se utiliza para obtener la información para cada una de las APIs, para el caso de Exchange tendremos la siguiente información:
           ``routes.IgnoreRoute(``"{resource}.axd/{*pathInfo}"``);
           ``routes.MapRoute(
               ``name: ``"Default"``,
               ``url: ``"{controller}/{action}/{id}"``,
               ``defaults: ``new { controller = ``"ExchangeSample"``, action = ``"Index"``, id = UrlParameter.Optional }
           ``);
       ``}
Una vez realizada esta modificación, compilamos la solución y si todo ha ido correctamente visualizaremos la imagen 5
Al pulsar sobre cada opción: Calendar, Mail o Contact, se mostrarán las distintas vistas añadidas donde visualizamos la información solicitada a la API correspondiente.
Dejo a la curiosidad de los lectores, añadir muchas más funcionalidades a este ejemplo base, como las operaciones CRUD sobre Calendar, Mail o Contacts.
Conclusiones
Office 365 es una plataforma que está creciendo cada vez más. Microsoft, piensa que el futuro es el "CLOUD" y que más pronto que tarde todas las empresas darán el salto. Personalmente, creo que hay productos que aún les falta cierta evolución para que las empresas se planteen dar el salto completo a la nube. Pero con novedades como las presentadas en Las Vegas, entre las que se encuentran estas APIs, cada vez hacen que la alternativa del cloud sea una opción más seria y más viable.
El poder utilizar las APIs desde aplicaciones fuera del entorno Office 365, es un gran adelanto y algo que facilitará la adopción de la plataforma. Hoy en dÃa, hay muchas empresas que requieren de aplicaciones para el envÃo de mails, para consultar información del directorio activo, o incluso gestionar calendarios entre los integrantes de su organización. Ahora mismo,  el obtener esta información mediante desarrollo es muy complejo y para solventar este inconveniente se planteaban escenarios hÃbridos. Pero esta solución es más cara y en algunos escenarios no dispones ni de las ventajas del cloud ni las ventajas de las infraestructuras propias. Con estas APIs todos estos requerimientos se podrán abordar de una forma simple y transparente.
En el siguiente número de CompartiMOSS desgranaremos las opciones que dispondremos para facilitar el trabajo con ficheros y carpetas en SharePoint/OneDrive como con el Active Directory.