Merge pull request #541 from octokit/shiftkey-patch-1

Getting Started With Octokit doc

docs/getting-started.md

@@ -0,0 +1,63 @@
+## Getting Started
+
+The easiest way to get started with Octokit is to use a plain `GitHubClient`:
+
+```
+var client = new GitHubClient(new ProductHeaderValue("my-cool-app"));
+```
+
+This will let you access unauthenticated GitHub APIs, but you will be subject to rate limiting (you can read more about this [here](https://developer.github.com/v3/#rate-limiting)).
+
+But why do you need this `ProductHeaderValue` value?
+
+The API will reject you if you don't provide a `User-Agent` header (more details [here](https://developer.github.com/v3/#user-agent-required)). This is also to identify applications that are accessing the API and enable GitHub to contact the application author if there are problems. So pick a name that stands out!
+
+### Authenticated Access
+
+If you want to access private repositories or perform actions on behalf of a user, you need to pass credentials to the client.
+
+There are two options supported by the API - basic and OAuth authentication.
+
+```
+var basicAuth = new Credentials("username", "password"); // NOTE: not real credentials
+client.Credentials = basicAuth;
+```
+
+```
+var tokenAuth = new Credentials("token"); // NOTE: not real token
+client.Credentials = tokenAuth;
+```
+
+It is **strongly recommended** to use the [OAuth Flow](https://github.com/octokit/octokit.net/blob/master/docs/oauth-flow.md) for interactions on behalf of a user, as this gives two significant benefits:
+
+ - the application owner never needs to store a user's password
+ - the token can be revoked by the user at a later date
+
+When authenticated, you have 5000 requests per hour available. So this is the recommended approach for interacting with the API.
+
+### Connecting to GitHub Enterprise
+
+Octokit also supports connecting to GitHub Enterprise environments - just provide the URL to your GitHub Enterprise server when creating the client.
+
+```
+var ghe = new Uri("https://github.myenterprise.com/");
+var client = new GitHubClient(new ProductHeaderValue("my-cool-app"), ghe);
+```
+
+### Get exploring
+
+Once you've got that setup, the simplest thing to experiment with is fetching details about a specific user:
+
+```
+var user = await client.User.Get("shiftkey");
+Console.WriteLine("{0} has {1} public repositories - go check out their profile at {1}",
+	user.Name,
+	user.PublicRepos,
+	user.Url);
+```
+
+If you've authenticated as a given user, you can query their details directly:
+
+```
+var user = await client.User.Current();
+```

docs/index.md

@@ -2,12 +2,16 @@
 
 This is a place for putting together some introductory documentation about how to use Octokit.net.
 
+ - [Getting Started](https://github.com/octokit/octokit.net/blob/master/docs/getting-started.md)
+ - [OAuth Flow](https://github.com/octokit/octokit.net/blob/master/docs/oauth-flow.md)
+ - [Releases API](https://github.com/octokit/octokit.net/blob/master/docs/releases.md)
+ - [Git Database API](https://github.com/octokit/octokit.net/blob/master/docs/releases.md)
+
+
 Possible topics to cover:
 
- - Authentication 
  - Working with Repositories
  - Working with User data
- - Working with Git data
  - Searching Repositories
  - ...
 
@@ -16,4 +20,5 @@ If you're not sure where to start, there's a suite of
 which can help you to get familiar with how things currently work.
 
 Love and Octocats,
+
 The Octokit.net Team

docs/oauth-flow.md

@@ -0,0 +1,100 @@
+## OAuth Flow
+
+If you have a service which needs to interact with the GitHub API on behalf of a user, you should use the OAuth flow. [Phil Haack](https://haacked.com) has written a great [blog post](http://haacked.com/archive/2014/04/24/octokit-oauth/) on using Octokit in ASP.NET, and even has a [demo project](https://github.com/Haacked/octokit-oauth-demo) you can try out, so this will just go over the specific APIs in more detail.
+
+### Setup
+
+First, you need to register your application on GitHub (or GitHub Enterprise). While logged in, go to your account settings and click the Applications tab. Then click "Register new application". 
+
+Or just navigate to [https://github.com/settings/applications/new](https://github.com/settings/applications/new) if you're lazy.
+
+Fill in some details about your application:
+
+![application registration](https://cloud.githubusercontent.com/assets/19977/2760125/62600c38-c9ae-11e3-911f-783d7a34aeaf.png)
+
+Then click "Register application", and you'll get your client id and client secret.
+
+![OAuth application registration details](https://cloud.githubusercontent.com/assets/19977/2760128/95587e40-c9ae-11e3-84f2-053d2574f1e8.png)
+
+### Starting the OAuth Flow
+
+We'll use these in a few places, so define these as private fields:
+
+```
+var clientId = "some-id-here";
+var clientSecret = "some-id-here";
+var client = new GitHubClient(new ProductHeaderValue("my-cool-app"));
+```
+
+To start the authentication flow, you need to craft a URL indicating your application needs to authenticate on behalf of the current user.
+
+```
+// NOTE: this is not required, but highly recommended!
+// ask the ASP.NET Membership provider to generate a random value 
+// and store it in the current user's session
+string csrf = Membership.GeneratePassword(24, 1);
+Session["CSRF:State"] = csrf;
+
+var request = new OauthLoginRequest(clientId)
+{
+    Scopes = {"user", "notifications"},
+    State = csrf
+};
+
+// NOTE: user must be navigated to this URL
+var oauthLoginUrl = client.Oauth.GetGitHubLoginUrl(request);
+```
+
+Scopes are keys which specify the permissions the application needs. If you don't specify a `Scopes` value, your application will only have read access to the user's public data (repository, user info, etc). There's lots of different scopes available for different interactions with user data, so have a look at the [documentation](https://developer.github.com/v3/oauth/#scopes) for more information.
+
+### Generating the token
+
+Once the user has been navigated to the URL above and clicked "Authorize Application", you will receive a callback at the default Callback URL for your application. If you require a more flexible URL, you can override this by specifying a different URL when creating the request.
+
+```
+var request = new OauthLoginRequest(clientId)
+{
+    // other parameters
+    RedirectUri = new Url("https://mycoolsite.com/some/uri")
+};
+```
+
+The callback will have two parameters, the code generated by the GitHub API and some additional state - this is specifically to prevent CSRF (Cross-Site Request Forgery) attacks and is highly recommended.
+
+With this code you can then request an access token by providing your client secret. This doesn't require any user interaction, so it can be done in the background.
+
+```
+public async Task<ActionResult> Authorize(string code, string state)
+{
+    if (String.IsNullOrEmpty(code))
+        return RedirectToAction("Index");
+
+    var expectedState = Session["CSRF:State"] as string;
+    if (state != expectedState) throw new InvalidOperationException("SECURITY FAIL!");
+    Session["CSRF:State"] = null;
+
+    var request = new OauthTokenRequest(clientId, clientSecret, code);
+    var token = await client.Oauth.CreateAccessToken(request);
+    Session["OAuthToken"] = token.AccessToken;
+
+    return RedirectToAction("Index");
+}
+```
+
+And now you have an access token, you can set up your credentials to use this token:
+
+```
+// repositories which include public and private repositories.
+public async Task<ActionResult> Index()
+{
+    var accessToken = Session["OAuthToken"] as string;
+    if (accessToken != null)
+    {
+        client.Credentials = new Credentials(accessToken);
+        
+        var repositories = await client.Repository.GetAllForCurrent();
+    }
+    
+    /* TODO: all the rest of the webapp */
+}
+```