Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Objective-C library for working with App.net.
Objective-C C
Branch: master

Fix bug making ANResponse.marker not work

@synthesize strikes again!
latest commit 877d35eda9
Brent Royal-Gordon authored
Failed to load latest commit information.
ANAccessTokenInformationRequest.h Declare AppNetKit to be MIT-licensed
ANAccessTokenInformationRequest.m Declare AppNetKit to be MIT-licensed
ANAnnotation.h Move ANDraftAnnotation into ANAnnotation.h
ANAnnotation.m Move ANDraftAnnotation into ANAnnotation.h
ANAuthenticatedRequest.h Turn requiresAccessToken into a class method
ANAuthenticatedRequest.m Turn requiresAccessToken into a class method
ANAuthenticator.h Add comments to ANAuthenticator explaining how to use it
ANAuthenticator.m Declare AppNetKit to be MIT-licensed
ANCompletions.h Support for stream markers
ANCreateFilterRequest.h Add ability to create and delete filters
ANCreateFilterRequest.m Add ability to create and delete filters
ANCreatePostRequest.h Declare AppNetKit to be MIT-licensed
ANCreatePostRequest.m Declare AppNetKit to be MIT-licensed
ANDefines.h Declare AppNetKit to be MIT-licensed
ANDeleteFilterRequest.h Add ability to create and delete filters
ANDeleteFilterRequest.m Add ability to create and delete filters
ANDeleteFiltersForUserRequest.h Add ability to create and delete filters
ANDeleteFiltersForUserRequest.m Add ability to create and delete filters
ANDeletePostRequest.h Declare AppNetKit to be MIT-licensed
ANDeletePostRequest.m Declare AppNetKit to be MIT-licensed
ANDraft.h Support for draft entities
ANDraft.m Support for draft entities
ANEntity.h Support for draft entities
ANEntity.m Wrap associated objects in a nice API
ANFilter.h Add filter-updating request
ANFilter.m Add filter-updating request
ANFilterRequest.h Support for filter reading requests
ANFilterRequest.m Support for filter reading requests
ANFiltersForCurrentUserRequest.h Support for filter reading requests
ANFiltersForCurrentUserRequest.m Support for filter reading requests
ANFollowUserRequest.h Declare AppNetKit to be MIT-licensed
ANFollowUserRequest.m Declare AppNetKit to be MIT-licensed
ANFollowersForUserRequest.h Declare AppNetKit to be MIT-licensed
ANFollowersForUserRequest.m Declare AppNetKit to be MIT-licensed
ANFollowingsForUserRequest.h Declare AppNetKit to be MIT-licensed
ANFollowingsForUserRequest.m Declare AppNetKit to be MIT-licensed
ANIdentifiedResource.h Extract a common superclass for ANUser and ANPost
ANIdentifiedResource.m Add an ID number to descriptions of ANIdentifiedResources
ANImage.h Retina support in ANImage
ANImage.m Retina support in ANImage
ANMuteUserRequest.h Declare AppNetKit to be MIT-licensed
ANMuteUserRequest.m Declare AppNetKit to be MIT-licensed
ANMutingsForUserRequest.h Declare AppNetKit to be MIT-licensed
ANMutingsForUserRequest.m Declare AppNetKit to be MIT-licensed
ANPost.h Declare AppNetKit to be MIT-licensed
ANPost.m Wrap associated objects in a nice API
ANPostRequest.h Declare AppNetKit to be MIT-licensed
ANPostRequest.m Turn requiresAccessToken into a class method
ANPostsByUserRequest.h Declare AppNetKit to be MIT-licensed
ANPostsByUserRequest.m Declare AppNetKit to be MIT-licensed
ANPostsInGlobalStreamRequest.h Declare AppNetKit to be MIT-licensed
ANPostsInGlobalStreamRequest.m Turn requiresAccessToken into a class method
ANPostsInUserStreamRequest.h Declare AppNetKit to be MIT-licensed
ANPostsInUserStreamRequest.m Declare AppNetKit to be MIT-licensed
ANPostsInUserUnifiedStreamRequest.h Add support for the new unified stream endpoint
ANPostsInUserUnifiedStreamRequest.m Add support for the new unified stream endpoint
ANPostsMentioningUserRequest.h Declare AppNetKit to be MIT-licensed
ANPostsMentioningUserRequest.m Declare AppNetKit to be MIT-licensed
ANPostsReplyingToPostRequest.h Declare AppNetKit to be MIT-licensed
ANPostsReplyingToPostRequest.m Declare AppNetKit to be MIT-licensed
ANPostsStarredByUserRequest.h Declare AppNetKit to be MIT-licensed
ANPostsStarredByUserRequest.m Declare AppNetKit to be MIT-licensed
ANPostsWithTagRequest.h Declare AppNetKit to be MIT-licensed
ANPostsWithTagRequest.m Turn requiresAccessToken into a class method
ANRepostPostRequest.h Declare AppNetKit to be MIT-licensed
ANRepostPostRequest.m Declare AppNetKit to be MIT-licensed
ANRequest.h Make ANRequest.session mutable
ANRequest.m Extract error messages from the envelope metadata section
ANRequestReturningPostList.h Declare AppNetKit to be MIT-licensed
ANRequestReturningPostList.m Declare AppNetKit to be MIT-licensed
ANResource+Magic.h Declare AppNetKit to be MIT-licensed
ANResource+Magic.m Wrap associated objects in a nice API
ANResource.h Note which requests require authentication
ANResource.m Wrap associated objects in a nice API
ANResponse.h Fix bug making ANResponse.marker not work
ANResponse.m Fix bug making ANResponse.marker not work
ANSession+ANResource_Private.h Abstract away the use of an NSHashTable
ANSession+Requests.h Support for stream markers
ANSession+Requests.m Support for stream markers
ANSession.h Support for stream markers
ANSession.m Avoid iOS 6/Mountain Lion-only construct
ANSource.h Declare AppNetKit to be MIT-licensed
ANSource.m Declare AppNetKit to be MIT-licensed
ANStarPostRequest.h Declare AppNetKit to be MIT-licensed
ANStarPostRequest.m Declare AppNetKit to be MIT-licensed
ANStreamMarker.h Support for stream markers
ANStreamMarker.m Support for stream markers
ANUnfollowUserRequest.h Declare AppNetKit to be MIT-licensed
ANUnfollowUserRequest.m Declare AppNetKit to be MIT-licensed
ANUnmuteUserRequest.h Declare AppNetKit to be MIT-licensed
ANUnmuteUserRequest.m Declare AppNetKit to be MIT-licensed
ANUnrepostPostRequest.h Declare AppNetKit to be MIT-licensed
ANUnrepostPostRequest.m
ANUnstarPostRequest.h Declare AppNetKit to be MIT-licensed
ANUnstarPostRequest.m Declare AppNetKit to be MIT-licensed
ANUpdateFilterRequest.h Add filter-updating request
ANUpdateFilterRequest.m Add filter-updating request
ANUpdateStreamMarkerRequest.h Support for stream markers
ANUpdateStreamMarkerRequest.m Support for stream markers
ANUser.h Declare AppNetKit to be MIT-licensed
ANUser.m Declare AppNetKit to be MIT-licensed
ANUserCounts.h Declare AppNetKit to be MIT-licensed
ANUserCounts.m Declare AppNetKit to be MIT-licensed
ANUserDescription.h Declare AppNetKit to be MIT-licensed
ANUserDescription.m
ANUserRequest.h Declare AppNetKit to be MIT-licensed
ANUserRequest.m Declare AppNetKit to be MIT-licensed
ANUsernameRequest.h Declare AppNetKit to be MIT-licensed
ANUsernameRequest.m Declare AppNetKit to be MIT-licensed
ANUsersMatchingSearchQueryRequest.h Declare AppNetKit to be MIT-licensed
ANUsersMatchingSearchQueryRequest.m Declare AppNetKit to be MIT-licensed
ANUsersWithPostRepostedRequest.h Declare AppNetKit to be MIT-licensed
ANUsersWithPostRepostedRequest.m Declare AppNetKit to be MIT-licensed
ANUsersWithPostStarredRequest.h Declare AppNetKit to be MIT-licensed
ANUsersWithPostStarredRequest.m Declare AppNetKit to be MIT-licensed
AppNetKit.h Support for filter reading requests
AppNetKit.m Declare AppNetKit to be MIT-licensed
ISO8601DateFormatter.h Initial check-in
ISO8601DateFormatter.m Initial check-in
NSDictionary+Parameters.h Declare AppNetKit to be MIT-licensed
NSDictionary+Parameters.m Declare AppNetKit to be MIT-licensed
NSDictionary+dictionaryWithObjectsForKeys.h Declare AppNetKit to be MIT-licensed
NSDictionary+dictionaryWithObjectsForKeys.m Declare AppNetKit to be MIT-licensed
NSObject+AssociatedObject.h Wrap associated objects in a nice API
NSObject+AssociatedObject.m Wrap associated objects in a nice API
NSString+AppNetExtensions.h Declare AppNetKit to be MIT-licensed
NSString+AppNetExtensions.m Declare AppNetKit to be MIT-licensed
README.md Declare AppNetKit to be MIT-licensed
_ANIdentifiedResourceSet.h Abstract away the use of an NSHashTable
_ANIdentifiedResourceSet.m Tweak comment indentation

README.md

AppNetKit

AppNetKit is an Objective-C library for communicating with the App.net Stream API. It is completely asynchronous, using blocks to notify you of completions.

AppNetKit covers the Token, Users, and Posts parts of the App.net API—all the portions available as of late August 2012.

Synopsis

ANSession.defaultSession.accessToken = myOAuthToken;

// Get the latest posts in the user's incoming post stream...
[ANSession.defaultSession postsInStreamWithCompletion:^(ANResponse * response, NSArray * posts, NSError * error) {
    if(!posts) {
        [self doSomethingWithError:error];
        return;
    }

    // Grab the most recent post.
    ANPost * latestPost = posts[0];

    // Compose a reply...
    ANDraft * newPost = [latestPost draftReply];
    newPost.text = [newPost.text appendString:@"Me too!"];  // The default text includes an @mention

    // And post it.
    [newPost createPostViaSession:ANSession.defaultSession completion:^(ANResponse * response, ANPost * post, NSError * error) {
        if(!post) {
            [self doSomethingWithError:error];
        }
    }];
}];

Quick Tour

ANAuthenticator

This is an OAuth helper singleton. Set the client ID and redirect URL, then use the other methods to help you generate OAuth URLs and parse out the accessToken from the response.

ANSession

ANSession is the central object in AppNetKit. Through it, you can fetch users and posts from App.net, create and delete posts, and do everything else the API permits.

You can create your own session using [[ANSession alloc] init] as usual, but if your app only requires one session, you can use [ANSession defaultSession] as a shortcut. Set your session's accessToken property to an OAuth token, then you can start working with App.net.

ANSession includes methods to perform most requests on the App.net API, from "fetch a user with a specific name" (-userWithUsername:completion:) to "fetch all posts with a specific hashtag between these two post IDs" (-postsWithTag:betweenID:andID:completion:).

These requests all take a completion handler--a block that will be called when the request has been completed. Completion handlers usually take three parameters:

  1. An ANResponse object containing metadata about your request. This parameter will be nil unless your app has enabled the "response_envelope" migration.

  2. The data you requested, as either a single ANResource object or an array of ANResource objects. If the request failed, this parameter will be nil.

  3. An NSError object. If the request succeeded, this parameter will be nil.

Some calls to retrieve posts take a pair of post IDs, and return only posts between those two IDs. The higher post ID should always be the first of those two parameters. If you don't want to provide one of these post IDs, pass the ANUnspecifiedPostID constant instead.

Calls to retrieve user-related data often take a user ID. If you want data for the currently logged-in user, you can pass the ANMeUserID constant for these parameters.

ANSession also manages UIApplication's network activity indicator. This should probably be configurable in various ways, not the least because it's the only way in which this library depends on iOS-specific APIs.

ANResource, ANUser, and ANPost

ANResource represents anything the server sends as a JSON object. Each ANResource has a representation property, which contains the object's JSON data parsed into Objective-C dictionaries, arrays, strings, etc. Each resource type has properties that convert this raw data to appropriate data types--from NSString for text data to NSTimeZone for an ANUser's timezone property.

Because ANResources represent data from the server, you cannot change them in any way, and you should not attempt to allocate them yourself. Instead, use ANRequest objects, ANSession methods, or helper methods on ANResource subclasses to retrieve them from App.net.

ANUser and ANPost are subclasses for the Stream API's User and Post objects, respectively. These classes (or rather their superclass, ANIdentifiedResource) are uniqued—fetching the same post or user from a given ANSession will always return the same ANUser or ANPost instance. That means that an ANUser or ANPost that you already have may be updated. Use key-value observing or register for the ANResourceDidUpdateNotification to find out when this happens.

Many ANResource objects have helper methods to perform common operations with them; for instance, ANUser has a -followWithCompletion: method, and ANPost has a -replyPostsWithCompletion: method. These are convenience methods which simply call the equivalent ANSession methods (in these cases, -followUserWithID:completion: and -postsReplyingToPostWithID:betweenID:andID:completion:).

Certain ANResource objects conform to the ANTextualResource protocol. These objects include a text property with plain text, an HTML property with HTML markup, and an entities property with entities covering portions of the plain text. You can use the same code to handle all ANTextualResources.

Related to resource objects is ANDraft, which represents a post that hasn't yet been created. You can create a draft yourself by using [[ANDraft alloc] init], or you can use a convenience method on another class, like -[ANPost replyDraft]. Post a reply with either -[ANDraft createPostViaSession:completion:] or -[ANSession createPostFromDraft:completion:].

ANRequest and subclasses

ANRequest subclasses represent specific API requests. You don't normally have to use them--ANSession has APIs for common requests--but they are public API, and using them directly can give you finer control than ANSession allows.

Create an ANRequest with the -initWithSession: constructor, then set whatever properties are available on that request and call -sendRequestWithCompletion: to perform the request. You can reuse the same request as many times as you'd like.

ANMutableRequest and ANMutableAuthenticatedRequest are also available for your use. These allow you to create your own requests to custom URLs. AppNetKit itself uses them to fetch images for the ANImage resource.

NSString+AppNetExtensions

AppNetKit adds two methods to NSString. -appNetUsernameString prepends an @ character to a username, and -appNetTagString prepends a # character.

Author

Brent Royal-Gordon, Architechies brent@architechies.com, @brent on App.net.

Please let me know if you use AppNetKit in a project. I'm curious about what people will do with this!

Bugs

A lot of the code in this library has never actually been run as I write this, so it's likely to have plenty of bugs. If you want to write unit tests to exercise all this code, I'll be happy to pull them in. (Packaging this mess as an Xcode project might be a good idea, too...)

Also note that my own development is for iOS 6; I don't believe there are any iOS 6-only APIs in AppNetKit, but it's possible a call or two snuck in. Again, patches are welcome.

If you find a problem, file an issue or write a patch and send it to me (preferably as a pull request, but I'm not picky).

Copyright

This software is licensed under the MIT license:

Copyright (C) 2012 Architechies.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Something went wrong with that request. Please try again.