Welcome the Alfresco Favorites API

[gmelahn]

You'll recall that in October of 2012, Alfresco announced the availability of the public Alfresco API.    This simple RESTful API makes it possible for developers to build exciting custom applications with your choice of programming language and tools.



But that was just the beginning.   Over the weekend, the Alfresco team was busy deploying some new extensions to the API set.   One of these, my new favourite, is the Favorites API.



 

The Favorites API

We all have our favorite Sites, Files and Folders.   And wouldn't it be nice to have an easy way in your code to get a list of your Favorites as well as add and remove Favorites?    Now there is!   



Getting a List of Favorites



In the spirit of REST, getting a list of your Favorites is just a matter of performing an HTTP GET of the favorites collection like this ...

HTTP GET /people/-me-/favorites

and what comes back is a list of your favorites, like this...

{

  'list' : {

    'pagination' : {

 'count' : 3,

 'hasMoreItems' : false,

 'totalItems' : 3,

 'skipCount' : 0,

 'maxItems' : 100

  },

     'entries' : [ {

 'entry' : {

  'targetGuid' : '1e365051-34af-4379-8a86-0b9bddc4ca9b',

  'target' : {

   'file' : {

    'name' : 'Beach.jpg',

    'title' : 'My Favorite Beach',

    'guid' : '1e365051-34af-4379-8a86-0b9bddc4ca9b',

    'createdAt' : '2013-01-15T23:17:30.636+0000',

    'modifiedAt' : '2013-01-15T23:20:40.841+0000',

    'createdBy' : 'greg.melahn@alfresco.com',

    'modifiedBy' : 'greg.melahn@alfresco.com',

    'mimeType' : 'image/jpeg',

    'sizeInBytes' : 12205,

    'versionLabel' : '1.2',

    'id' : '1e365051-34af-4379-8a86-0b9bddc4ca9b'

   }

  }

 }

  }, {

 'entry' : {

  'targetGuid' : '690745a5-094a-4a97-bf40-434f9751c2c9',

  'target' : {

   'folder' : {

    'name' : 'Attachments',

    'guid' : '690745a5-094a-4a97-bf40-434f9751c2c9',

    'createdAt' : '2013-01-21T23:45:56.933+0000',

    'modifiedAt' : '2013-01-21T23:45:56.933+0000',

    'createdBy' : 'greg.melahn@alfresco.com',

    'modifiedBy' : 'greg.melahn@alfresco.com',

    'id' : '690745a5-094a-4a97-bf40-434f9751c2c9'

   }

  }

 }

  }, {

 'entry' : {

  'createdAt' : '2013-04-09T21:22:21.767+0000',

  'targetGuid' : 'df40f96c-c874-4540-a7f2-8b1a58b14832',

  'target' : {

   'site' : {

    'id' : 'pie',

    'guid' : 'df40f96c-c874-4540-a7f2-8b1a58b14832',

    'title' : 'PIE',

    'description' : 'PIE team',

    'visibility' : 'PUBLIC',

              'role' : 'SiteManager'

    }

   }

  }

 } 

    ]

}

Notice in the list you see an instance of a Site, a Folder and a File along with useful information about each entity.   For example, in the case of the Site object, you see your role in that Site.  That extra information saves you the trouble of making another request to get more information (avoiding that trip back to the server is particularly important for mobile apps).  Also, notice the list is in the same standard format we introduced when the Alfresco Public API was published last year.



And because it's just a JSON object, you can easily consume the list with a few lines of JavaScript like this...

   function saveFavorites(favReq) { 

      var myFavorites = JSON.parse(favReq.responseText); 

      $.each(myFavorites.list.entries, function(index, value) {    

         favorites.push(value.entry.target.site.id); 

         } 

      ); 

   }

Adding a New Favorite

Now what if you want to add a new Favorite?    Easy.   Just perform an HTTP POST to the favorites collection like this ...

HTTP POST /people/-me-/favorites 

     { 

       'target': { 

          'site' : { 

             'guid' : '8ac18731-601b-4bb4-be1a-cd5d252cce3f' 

           }  

        } 

     }

The result is an HTTP Status of 201 which means the object is now a Favorite, and a JSON object is returned with useful information about the new Favorite.

   

 { 

       'entry' : {  

          'targetGuid' : '8ac18731-601b-4bb4-be1a-cd5d252cce3f', 

          'createdAt' : '2012-07-20T21:46:09.659+0000',     

          'target': {     

             'site' : {       

                'id' : 'foo', 

                'guid' : '8ac18731-601b-4bb4-be1a-cd5d252cce3f', 

                'title' : 'A Few of My Favorite Things', 

                'visibility' : 'PRIVATE', 

                'description' : 'The Favorite Site', 

                'role' : 'SiteManager” 

              } 

           } 

        }  

     }

Removing a Favorite

Should you decide that something is no longer a Favorite, just perform an HTTP DELETE on the entry in the favorites collection, like this ...

   

HTTP DELETE /people/-me-/favorites/8ac18731-601b-4bb4-be1a-cd5d252cce3f

and the result is an HTTP Status Code of 204 (No Content).   Note this does not delete the object itself (the Site in this example), just the fact that it is a Favorite.

Summary

That's just a brief introduction, but hopefully I've given you a taste of the new API.



If you want to start using the Alfresco API, just register for a free developer key and download the Reference Guide.



And there's more, so stay tuned!   Look for a post about another new API that allows you to request access to Sites.