Working with pagination and meta

Meta

Along with each response, you get three things. A response object, a meta object, and an error (which of course is nil if there wasn't a problem). The meta object contains a few properties that are particularly interesting or useful:

@property (assign) NSUInteger statusCode;
@property (strong) NSString *maxID;
@property (strong) NSString *minID;
@property (assign) BOOL moreDataAvailable;
@property (strong) ANKStreamMarker *marker;

One of the most interesting reason to care about this object is pagination.

Pagination

The pagination API lets you control the [pagination parameters] (http://developers.app.net/docs/basics/pagination/#parameters) that many resource fetches respect.

Changing default pagination settings

Each ANKClient has a pagination property, which is an instance of ANKPaginationSettings. ANKPaginationSettings has the following properties which will affect the pagination used by the server when generating the response:

@property (strong) NSString *sinceID;
@property (strong) NSString *beforeID;
@property (assign) NSUInteger count;

// stream marker
@property (strong) NSString *lastReadID;
@property (strong) NSString *lastReadIDInclusive;
@property (strong) NSString *markerID;
@property (strong) NSString *markerIDInclusive;

The simplest way to change the pagination settings you're using is to set the previously mentioned pagination property on your ANKClient instance. This will set the count to 50 for all requests (keep in mind that only requests that support the pagination API will use this - it will not impact other requests).

[ANKClient sharedClient].pagination = [ANKPaginationSettings settingsWithCount:50];

Fetch more (than 20) of a resource

ANKClient has a method called clientWithPagination: that takes an ANKPaginationSettings objects and returns a new ANKClient with those pagination settings. You do not have to do anything set this new ANKClient up, it will be authorized and ready to go.

That allows for code such as this to fetch, say, 50 posts instead of the default 20:

[[self.client clientWithPagination:[ANKPaginationSettings settingsWithCount:50]] fetchUnifiedStreamForCurrentUserWithCompletion:^(NSArray *posts, ANKAPIResponseMeta *meta, NSError *error) {
	// posts will contain 50 objects
}

Fetch all

Here is an example that fetches all of the current user's files, regardless of if they fit in the same response payload or not. Please note that you could also set the count on pagination settings to be higher (up to 200 as per the docs), and this would take less API calls.

// create a copied client to use so that default pagination settings aren't touched
ANKClient *paginatedClient = [self.client copy];
__block BOOL isMore = YES;
		
dispatch_semaphore_t semaphore = dispatch_semaphore_create(0);
dispatch_queue_t queue = dispatch_queue_create("paginationQueue", DISPATCH_QUEUE_CONCURRENT);
		
dispatch_async(queue, ^{
	while (isMore) {
		// note that we make requests directly with the paginatedClient instead of self.client
		[paginatedClient fetchCurrentUserFilesWithCompletion:^(id responseObject, ANKAPIResponseMeta *meta, NSError *error) {
			NSLog(@"files: %@", responseObject);
					
			// update the pagination so that the next fetch is for the next page of objects
			paginatedClient.pagination.beforeID = meta.minID;
					
			// update isMore to reflect if there is more data available
			isMore = meta.moreDataAvailable;
					
			// signal that we are ready for the next iteration of the while loop
			dispatch_semaphore_signal(semaphore);
		}];
		
		// wait for the signal from the completion block
		dispatch_semaphore_wait(semaphore, DISPATCH_TIME_FOREVER);
	}			
}