How to use ADNKit

This document is meant to provide a basic overview of the structure and design of the framework. There are two main components in ADNKit - the model layer, and ANKClient.

The Model Layer

The model classes each represent a different type of object you can either send or receive from the server. Their job is to encapsulate the properties of each type of object. In many cases they also have convenience methods for making some specific task easier and less painful. No networking is done in the model layer.

All model classes inherit from ANKResource. ANKResource is kind of a mix between Mantle and JSONModel, but it's smaller and much simpler and has many fewer features. It's main job is to create an instance of a model object from a JSON dictionary, and create a JSON dictionary from a model object, all while having enough logic to keep each subclass tiny and free of duplicated code. Most model objects are a direct subclass of ANKResource.

However, some model objects are a subclass of ANKAnnotatableResource (which is itself a subclass of ANKResource). This class adds an annotations array to the class, which enables annotations on all subclasses(ANKChannel, ANKFile, ANKMessage, ANKPost, and ANKUser). More info on annotations themselves, and more info on using annotations in ADNKit.

Many APIs accept model objects themselves, so don't be afraid to alloc/init them and directly set the properties you're interested in. The networking APIs often provide more features and conveniences when passed a model object instead of raw parameters.

ANKPost *post = [[ANKPost alloc] init];
post.text = @"Hello, world!";
post.annotations = @[[ANKAnnotation annotationWithType:@"com.example.awesome" value:@{@"ADNKit is": @"awesomeeeee"}];

ANKClient

ANKClient itself is a subclass of AFHTTPClient and provides authentication, pagination, and General Parameters APIs. All App.net services integration is done in categories on ANKClient to keep it modular and keep the file sizes as small as possible. For example, ANKUser.h/.m is the model class for User, while ANKClient+ANKUser.h/.m is all networking calls related to Users. Because of this architecture, ANKClient is your bridge to the server. Any time you need to perform any operation that involves the server, you will be doing it through an ANKClient instance.

ANKPost *post = [[ANKPost alloc] init];
post.text = @"Hello, world!";
post.annotations = @[[ANKAnnotation annotationWithType:@"com.example.awesome" value:@{@"ADNKit is": @"awesomeeeee"}];

[[ANKClient sharedClient] createPost:post completion:void (^)(id responseObject, ANKAPIResponseMeta *meta, NSError *error) {
	if (!error) {
		NSLog(@"post sent!");
	}
}];

ANKClient provides a singleton sharedClient, but keep in mind that each ANKClient instance (including the shared instance) represents a single authenticated user. [So then what if I want to have multiple users logged in, you ask?] (https://github.com/joeldev/ADNKit/wiki/Supporting-multiple-logged-in-Users). It's very easy.

ANKClient also implements NSCopying, and is a designed to be copied and modified. Need an ANKClient instance with a few settings that are unique to certain areas of your application? Copy the ANKClient, set the custom settings, and make calls using that client. One example might be fetching annotations - you may only want to fetch annotations for one or two specific requests in your application, and setting up an ANKClient copy with includeAnnotations enabled is a very easy way to solve that problem.

Tips for Getting Started

The best way to get started is to dive right in and start writing an app! Review the other pages on the wiki and start coding. It's also good to review the Tips and Tricks document to have an understanding of what else ADNKit brings to the table beyond the model layer and ANKClient.

Feel free to file issues for bugs, feature requests, questions, and really anything else. Enjoy!