Working with Annotations

[Annotations] (http://developers.app.net/docs/meta/annotations/) are a pretty critical part of the App.net arsenal, and ADNKit provides a few features to make them easier to use.

Fetching Annotations

Currently, the only way annotations can be fetched is by setting the shouldRequestAnnotations property on an ANKClient to YES. In the future there will be a better resource-specific API, but if you set this to YES all calls will request annotations. You do not need to do anything else other than set this property once and you are good to go.

[ANKClient sharedClient].shouldRequestAnnotations = YES;

ANKAnnotatableResource

The superclass for any model object that supports annotations is ANKAnnotatableResource instead of ANKResource. ANKAnnotatableResource provides the following interface:

@interface ANKAnnotatableResource : ANKResource

@property (strong) NSArray *annotations;

@end

Subclasses include Channel, File, Message, Post, and User. The annotations array is expected to be an array of ANKAnnotations.

ANKAnnotation

ANKAnnotation is a representation of a single annotation in an ANKAnnotatableResource's annotations array.

ANKAnnotation provides many useful APIs, the most basic of which is:

+ (instancetype)annotationWithType:(NSString *)type value:(NSDictionary *)value;

This allows you to easily create annotations with minimal code:

ANKPost *post = [[ANKPost alloc] init];
post.text = @"This post has an annotation attached to it!";
post.annotations = @[[ANKAnnotation annotationWithType:@"com.example.awesome" value:@{@"annotations work": @"beautifully"}]];

When this annotations array is encoded to JSON, it will result in the following:

[
    {
        "type": "com.example.awesome",
        "value": {
            "annotations work": "beautifully"
        }
    }
]

Resource Integration

The annotations API is closely tied in with the model object layer, since there are many cases in which you want to attach a model object in an annotation. Here is a simple example of attaching a place to a post:

ANKPlace *place; // a valid place object that you have already
ANKPost *post = [[ANKPost alloc] init];
post.text = @"This post has a place attached to it!";
post.annotations = @[[ANKAnnotation annotationWithType:@"com.example.place" object:place]];

And let's say that later you fetch a post and find that it has this annotation type ("com.example.place"), the only thing you have to do to get that Place object back out is ask for it:

ANKPost *post; // a post that you fetched
ANKAnnotation *annotation = post.annotations[0]; // after having checked count and all that
ANKPlace *place = [annotation resourceOfClassForValue:[ANKPlace class]];

Attaching an ANKFile to an ANKMessage or ANKPost as an OEmbed

ANKFile *file = [[ANKFile alloc] init];
// [[ANKClient sharedClient] createFile:file ... (etc, create the file on the server)

// now when you're ready to make the post:
ANKPost *post = [[ANKPost alloc] init];
post.text = @"embedded media is fun!";
post.annotations = @[[ANKAnnotation oembedAnnotationForFile:file]];
[[ANKClient sharedClient] createPost:post completion:nil]; // create the post, probably not passing nil as the completion in your case

Core Annotations

[Core annotations] (http://developers.app.net/docs/meta/annotations/#core-annotations) are a standard set of annotation types and expected value formats that can be used to support the same feature across multipe applications without each application having to create their own custom annotation type. It is a very good idea to use a core annotation to solve your problem, if one exists for the situation.

ANKAnnotation provides a number of convenience methods for creating core annotations without needing to know any keys or data formats.

+ (instancetype)attachmentsAnnotationWithFiles:(NSArray *)files;
+ (instancetype)channelInviteAnnotationForChannel:(ANKChannel *)channel;
+ (instancetype)checkinAnnotationForPlace:(ANKPlace *)place;
+ (instancetype)externalCrosspostAnnotationWithURL:(NSURL *)canonicalURL;
+ (instancetype)userBlogAnnotationWithURL:(NSURL *)URL;
+ (instancetype)userFacebookIDAnnotationWithID:(NSString *)ID;
+ (instancetype)userHomepageAnnotationWithURL:(NSURL *)URL;
+ (instancetype)userTwitterAccountNameWithString:(NSString *)twitterName;
+ (instancetype)fallbackURLAnnotationWithURL:(NSURL *)URL;
+ (instancetype)geolocationAnnotationForGeolocation:(ANKGeolocation *)geolocation;
+ (instancetype)languageAnnotationForLanguageIdentifier:(NSString *)languageIdentifier;
+ (instancetype)oembedAnnotationForOEmbed:(ANKOEmbed *)oembed;
+ (instancetype)oembedAnnotationForFile:(ANKFile *)file;