NOTE: This repository is no longer supported or updated by GitHub. If you wish to continue to develop this code yourself, we recommend you fork it.
OctoKit is a Cocoa and Cocoa Touch framework for interacting with the GitHub API, built using AFNetworking, Mantle, and ReactiveCocoa.
In order to begin interacting with the API, you must instantiate an OCTClient. There are two ways to create a client without authenticating:
-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.+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.
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.
}];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.
}];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];
}];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];
}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"];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.
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];
}
}];
}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.
}
}];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.
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:
- Add the OctoKit repository as a submodule of your application's repository.
- Run
script/bootstrapfrom within the OctoKit folder. - Drag and drop
OctoKit.xcodeproj,OctoKitDependencies.xcodeproj,ReactiveCocoa.xcodeproj, andMantle.xcodeprojinto the top-level of your application's project file or workspace. The latter three projects can be found within theExternalfolder. - On the "Build Phases" tab of your application target, add the following to the "Link Binary With Libraries" phase:
- On iOS, add the
.alibraries for OctoKit, AFNetworking, and ISO8601DateFormatter. - On OS X, add the
.frameworkbundles for OctoKit, ReactiveCocoa, Mantle, AFNetworking, and ISO8601DateFormatter. All of the frames must also be added to any "Copy Frameworks" build phase.
- On iOS, add the
- 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). - For iOS targets, add
-ObjCto 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.
This is only needed on OS X.
- Go to the "Build Phases" tab of your application target.
- If you don't already have one, add a "Copy Files" build phase and target the "Frameworks" destination.
- Drag
OctoKit.frameworkfrom the OctoKit project’sProductsXcode group into the "Copy Files" build phase you just created (or the one that you already had). - A reference to the framework will now appear at the top of your application’s Xcode group, select it and show the "File Inspector".
- Change the "Location" to "Relative to Build Products".
- Now do the same (starting at step 2) for the frameworks within the External folder.
OctoKit is released under the MIT license. See LICENSE.md.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent