Latest 0.5
Homepage https://github.com/octokit/octokit.objc
License MIT
Platforms ios 5.1, osx 10.7, requires ARC
Dependencies AFNetworking, ISO8601DateFormatter, Mantle, ReactiveCocoa
Authors

OctoKit is a Cocoa and Cocoa Touch framework for interacting with the GitHub
API
, built using
AFNetworking,
Mantle, and
ReactiveCocoa.

Making Requests

In order to begin interacting with the API, you must instantiate an
OCTClient. There are two ways to create a client without
authenticating:

  1. -initWithServer: is the most basic way to initialize a client. It accepts
    an OCTServer, which determines whether to connect to
    GitHub.com or a GitHub Enterprise instance.
  2. +unauthenticatedClientWithUser: is similar, but lets you set an active
    user
    , which is required for certain requests.

We’ll focus on the second method, since we can do more with it. Let’s create
a client that connects to GitHub.com:

OCTUser *user = [OCTUser userWithRawLogin:username server:OCTServer.dotComServer];
OCTClient *client = [OCTClient unauthenticatedClientWithUser:user];

After we’ve got a client, we can start fetching data. Each request method on
OCTClient returns
a ReactiveCocoa signal, which
is kinda like a future or
promise
:

// Prepares a request that will load all of the user's repositories, represented
// by `OCTRepository` objects.
//
// Note that the request is not actually _sent_ until you use one of the
// -subscribe… methods below.
RACSignal *request = [client fetchUserRepositories];

However, you don’t need a deep understanding of RAC to use OctoKit. There are
just a few basic operations to be aware of.

Receiving results one-by-one

It often makes sense to handle each result object independently, so you can
spread any processing out instead of doing it all at once:

// This method actually kicks off the request, handling any results using the
// blocks below.
[request subscribeNext:^(OCTRepository *repository) {
    // This block is invoked for _each_ result received, so you can deal with
    // them one-by-one as they arrive.
} error:^(NSError *error) {
    // Invoked when an error occurs.
    //
    // Your `next` and `completed` blocks won't be invoked after this point.
} completed:^{
    // Invoked when the request completes and we've received/processed all the
    // results.
    //
    // Your `next` and `error` blocks won't be invoked after this point.
}];

Receiving all results at once

If you can’t do anything until you have all of the results, you can "collect"
them into a single array:

[[request collect] subscribeNext:^(NSArray *repositories) {
    // Thanks to -collect, this block is invoked after the request completes,
    // with _all_ the results that were received.
} error:^(NSError *error) {
    // Invoked when an error occurs. You won't receive any results if this
    // happens.
}];

Receiving results on the main thread

The blocks in the above examples will be invoked in the background, to avoid
slowing down the main thread. However, if you want to run UI code, you shouldn’t
do it in the background, so you must "deliver" results to the main thread
instead:

[[request deliverOn:RACScheduler.mainThreadScheduler] subscribeNext:^(OCTRepository *repository) {
    // ...
} error:^(NSError *error) {
    UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"Whoops!"
                                                    message:@"Something went wrong."
                                                   delegate:nil
                                          cancelButtonTitle:nil
                                          otherButtonTitles:nil];
    [alert show];
} completed:^{
    [self.tableView reloadData];
}];

Cancelling a request

All of the -subscribe… methods actually return
a RACDisposable
object. Most of the time, you don’t need it, but you can hold onto it if you
want to cancel requests:

- (void)viewWillAppear:(BOOL)animated {
    [super viewWillAppear:animated];

    RACDisposable *disposable = [[[[self.client
        fetchUserRepositories]
        collect]
        deliverOn:RACScheduler.mainThreadScheduler]
        subscribeNext:^(NSArray *repositories) {
            [self addTableViewRowsForRepositories:repositories];
        } error:^(NSError *error) {
            UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"Whoops!"
                                                            message:@"Something went wrong."
                                                           delegate:nil
                                                  cancelButtonTitle:nil
                                                  otherButtonTitles:nil];
            [alert show];
        }];

    // Save the disposable into a `strong` property, so we can access it later.
    self.repositoriesDisposable = disposable;
}

- (void)viewWillDisappear:(BOOL)animated {
    [super viewWillDisappear:animated];

    // Cancels the request for repositories if it's still in progress. If the
    // request already terminated, nothing happens.
    [self.repositoriesDisposable dispose];
}

Authentication

OctoKit supports two variants of OAuth2
for signing in. We recommend the browser-based
approach
, but you can also implement a native
sign-in flow
if desired.

In both cases, you will need to register your OAuth
application
, and provide OctoKit
with your client ID and client secret before trying to authenticate:

[OCTClient setClientID:@"abc123" clientSecret:@"654321abcdef"];

Signing in through a browser

With this API, the user will be redirected to their default browser (on OS X) or
Safari (on iOS) to sign in, and then redirected back to your app. This is the
easiest approach to implement, and means the user never has to enter their
password directly into your app — plus, they may even be signed in through the
browser already!

To get started, you must implement a custom URL
scheme

for your app, then use something matching that scheme for your OAuth
application’s
callback URL. The
actual URL doesn’t matter to OctoKit, so you can use whatever you’d like, just
as long as the URL scheme is correct.

Whenever your app is opened from your URL, or asked to open it, you must pass it
directly into OCTClient:

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)URL sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
    // For handling a callback URL like my-app://oauth
    if ([URL.host isEqual:@"oauth"]) {
        [OCTClient completeSignInWithCallbackURL:URL];
        return YES;
    } else {
        return NO;
    }
}

After that’s set up properly, you can present the sign in page at any point. The
pattern is very similar to making a request, except that you
receive an OCTClient instance as a reply:

[[OCTClient
    signInToServerUsingWebBrowser:OCTServer.dotComServer scopes:OCTClientAuthorizationScopesUser]
    subscribeNext:^(OCTClient *authenticatedClient) {
        // Authentication was successful. Do something with the created client.
    } error:^(NSError *error) {
        // Authentication failed.
    }];

You can also choose to receive the client on the main
thread
, just like with any other request.

Signing in through the app

If you don’t want to open a web page, you can use the native authentication flow
and implement your own sign-in UI. However, two-factor
authentication

makes this process somewhat complex, and the native authentication flow may not work
with GitHub Enterprise instances that use single
sign-on
.

Whenever the user wants to sign in, present your custom UI. After the form has
been filled in with a username and password (and perhaps a server URL, for GitHub
Enterprise users), you can attempt to authenticate. The pattern is very similar to
making a request, except that you receive an OCTClient instance
as a reply:

OCTUser *user = [OCTUser userWithRawLogin:username server:OCTServer.dotComServer];
[[OCTClient
    signInAsUser:user password:password oneTimePassword:nil scopes:OCTClientAuthorizationScopesUser]
    subscribeNext:^(OCTClient *authenticatedClient) {
        // Authentication was successful. Do something with the created client.
    } error:^(NSError *error) {
        // Authentication failed.
    }];

(You can also choose to receive the client on the main
thread
, just like with any other
request.)

oneTimePassword must be nil on your first attempt, since it’s impossible to
know ahead of time if a user has two-factor authentication enabled. If they do,
you’ll receive an error of code
OCTClientErrorTwoFactorAuthenticationOneTimePasswordRequired, and should
present a UI for the user to enter the 2FA code they received via SMS or read
from an authenticator app.

Once you have the 2FA code, you can attempt to sign in again. The resulting code
might look something like this:

- (IBAction)signIn:(id)sender {
    NSString *oneTimePassword;
    if (self.oneTimePasswordVisible) {
        oneTimePassword = self.oneTimePasswordField.text;
    } else {
        oneTimePassword = nil;
    }

    NSString *username = self.usernameField.text;
    NSString *password = self.passwordField.text;

    [[[OCTClient
        signInAsUser:username password:password oneTimePassword:oneTimePassword scopes:OCTClientAuthorizationScopesUser]
        deliverOn:RACScheduler.mainThreadScheduler]
        subscribeNext:^(OCTClient *client) {
            [self successfullyAuthenticatedWithClient:client];
        } error:^(NSError *error) {
            if ([error.domain isEqual:OCTClientErrorDomain] && error.code == OCTClientErrorTwoFactorAuthenticationOneTimePasswordRequired) {
                // Show OTP field and have the user try again.
                [self showOneTimePasswordField];
            } else {
                // The error isn't a 2FA prompt, so present it to the user.
                [self presentError:error];
            }
        }];
}

Choosing an authentication method dynamically

If you really want a native login flow without
sacrificing the compatibility of browser-based
login
, you can inspect a server’s metadata
to determine how to authenticate.

However, because not all GitHub Enterprise servers support this API, you should
handle any errors returned:

[[OCTClient
    fetchMetadataForServer:someServer]
    subscribeNext:^(OCTServerMetadata *metadata) {
        if (metadata.supportsPasswordAuthentication) {
            // Authenticate with +signInAsUser:password:oneTimePassword:scopes:
        } else {
            // Authenticate with +signInToServerUsingWebBrowser:scopes:
        }
    } error:^(NSError *error) {
        if ([error.domain isEqual:OCTClientErrorDomain] && error.code == OCTClientErrorUnsupportedServer) {
            // The server doesn't support capability checks, so fall back to one
            // method or the other.
        }
    }];

Saving credentials

Generally, you’ll want to save an authenticated OctoKit session, so the user
doesn’t have to repeat the sign in process when they open your app again.

Regardless of the authentication method you use, you’ll end up with an
OCTClient instance after the user signs in successfully. An authenticated
client has user and token properties. To remember the user, you need to save
user.rawLogin and the OAuth access token into the
keychain.

When your app is relaunched, and you want to use the saved credentials, skip the
normal sign-in methods and create an authenticated client directly:

OCTUser *user = [OCTUser userWithRawLogin:savedLogin server:OCTServer.dotComServer];
OCTClient *client = [OCTClient authenticatedClientWithUser:user token:savedToken];

If the credentials are still valid, you can make authenticated requests
immediately. If not valid (perhaps because the OAuth token was revoked by the
user), you’ll receive an error after sending your first request, and can ask the
user to sign in again.

Importing OctoKit

OctoKit is still new and moving fast, so we may make breaking changes from
time-to-time, but it has partial unit test coverage and is already being used
in GitHub for Mac‘s production code.

To add OctoKit to your application:

  1. Add the OctoKit repository as a submodule of your application’s
    repository.
  2. Run script/bootstrap from within the OctoKit folder.
  3. Drag and drop OctoKit.xcodeproj, OctoKitDependencies.xcodeproj,
    ReactiveCocoa.xcodeproj, and Mantle.xcodeproj into the top-level of your
    application’s project file or workspace. The latter three projects can be
    found within the External folder.
  4. On the "Build Phases" tab of your application target, add the following to the "Link Binary With Libraries" phase:
    • On iOS, add the .a libraries for OctoKit, AFNetworking, and ISO8601DateFormatter.
    • On OS X, add the .framework bundles for OctoKit, ReactiveCocoa, Mantle, AFNetworking, and ISO8601DateFormatter. All of the frames must also be
      added to any "Copy Frameworks" build phase.
  5. Add $(BUILD_ROOT)/../IntermediateBuildFilesPath/UninstalledProducts/include $(inherited) to the "Header Search Paths" build setting (this is only
    necessary for archive builds, but it has no negative effect otherwise).
  6. For iOS targets, add -ObjC to the "Other Linker Flags" build setting.

If you would prefer to use CocoaPods, there are some OctoKit podspecs
that have been generously contributed by third parties.

If you’re developing OctoKit on its own, then use OctoKit.xcworkspace.

Copying the frameworks

This is only needed on OS X.

  1. Go to the "Build Phases" tab of your application target.
  2. If you don’t already have one, add a "Copy Files" build phase and target
    the "Frameworks" destination.
  3. Drag OctoKit.framework from the OctoKit project’s Products Xcode group
    into the "Copy Files" build phase you just created (or the one that you
    already had).
  4. A reference to the framework will now appear at the top of your
    application’s Xcode group, select it and show the "File Inspector".
  5. Change the "Location" to "Relative to Build Products".
  6. Now do the same (starting at step 2) for the frameworks within the External
    folder.

License

OctoKit is released under the MIT license. See
LICENSE.md.

Latest podspec

{
    "name": "OctoKit",
    "version": "0.5",
    "summary": "GitHub API client for Objective-C.",
    "homepage": "https://github.com/octokit/octokit.objc",
    "license": "MIT",
    "authors": {
        "GitHub": "[email protected]"
    },
    "source": {
        "git": "https://github.com/octokit/octokit.objc.git",
        "tag": "0.5"
    },
    "source_files": "OctoKit",
    "requires_arc": true,
    "platforms": {
        "ios": "5.1",
        "osx": "10.7"
    },
    "prepare_command": "    find . -regex '.*\.[hm]' -exec sed -i '' -E '[email protected]@@' {} \;n",
    "dependencies": {
        "AFNetworking": [
            "~> 1.3.3"
        ],
        "ISO8601DateFormatter": [
            "~> 0.7.0"
        ],
        "Mantle": [
            "~> 1.3.1"
        ],
        "ReactiveCocoa": [
            "~> 2.2.2"
        ]
    }
}

Pin It on Pinterest

Share This