SpringSource/spring-social-facebook — pull request #3 by karthicks (2011-10-20 07:01:06+00:00)
Title: Access Ads On The Facebook Graph API

More often than not, the [Facebook Graph API](http://developers.facebook.com/docs/reference/api) is used to access users, statuses, events and what-not. In addition, it comes with a [Ads API](http://developers.facebook.com/docs/reference/ads-api/) that specifically deals with ads, which can be used to "automate the creation of ads campaigns on Facebook, as well as measure the performance of ad campaigns".

Herein, we propose extending the Spring Social Facebook project to handle Facebook Ads through the Graph API (as opposed to their legacy REST API), by leveraging the existing framework that's already in place. In particular, we'll talk about the abstract models and operations, followed by their concrete template and format definitions. Last but not the least, we'll go into certain generic features that we feel belong in the Graph API layer.

* Ad API Objects: At the top-level, we need Java objects corresponding to the AdAccount, AdAccountGroup, AdCampaign, AdCreative and AdGroup Graph API objects. While most of the fields are primitive types, some reference embedded objects such as User, Stats, etc, not to mention enumerations such as AccountStatus, BidType, Permission and UserRole.

* Ad API Operations: At the top-level, we define a FacebookAds interface, which along the lines of the Facebook interface, is broken down into sub-APIs corresponding to AccountOperations, AccountGroupOperations, CampaignOperations, CreativeOperations, and AdGroupOperations. Most of those operations allow fetching, updating and deleting the underlying object type. In addition, some let you do things like fetch statistics, estimate reach, etc.

* Ad Operation Templates: At the top-level, we implement the aforementioned operations as a FacebookAdsTemplate, much like the FacebookTemplate. The object-specific templates, viz., AccountTemplates, AccountGroupTemplates, CampaignTemplates, CreativeTemplates and AdGroupTemplates delegate most of the work to the underlying graphApi object.

* Ad Object Formats: For the most part, the JSON objects the Graph API understands map directly to the POJO properties. However, there are some cases where the field names did not match, and other cases where a custom deserializer is called for. In order to make the mapping of the Java to JSON objects seamless, we introduced certain Jackson mixin classes.

* Graph API Extensions: Considering that most Graph API objects, including the ad-specific ones, are connected to each other, we felt compelled to extend the GraphAPI interface to handle additions and deletions of connections. In addition, we added a way to update a Graph API object (that unlike the publish method does not require a connection object). Moreover, we implemented a ConnectionTemplate abstract class, which serves as the base class for all of the ad operation templates above.

The goal of the patch that will follow is primarily to (a) serve as a starting point (b) invite inputs on design approach and (c) allow the community at large to work on this together. In other words, this is a work in progress.