diff --git a/PocketSharp/Components/Authentification.cs b/PocketSharp/Components/Authentification.cs index f9308cf..136ea88 100644 --- a/PocketSharp/Components/Authentification.cs +++ b/PocketSharp/Components/Authentification.cs @@ -11,22 +11,48 @@ namespace PocketSharp public partial class PocketClient { /// - /// Gets the authentification URI. + /// Retrieves the requestCode from Pocket. /// - /// The callback URI. /// - public Uri Authenticate(Uri callbackUri) + public string GetRequestCode() { - RequestCode response = Get("oauth/request", new List() + // check if request code is available + if (CallbackUri == null) { - new Parameter() { Name = "redirect_uri", Value = callbackUri, Type = ParameterType.GetOrPost } - }); + throw new APIException("Authentication methods need a callbackUri on initialization of the PocketClient class"); + } + + // do request + RequestCode response = Get("oauth/request", Utilities.CreateParamInList("redirect_uri", CallbackUri)); // save code to client RequestCode = response.Code; // generate redirection URI and return - return new Uri(string.Format(authentificationUrl, RequestCode, Uri.EscapeDataString(callbackUri.ToString()))); + return RequestCode; + } + + + /// + /// Generate Authentication URI from requestCode + /// + /// The requestCode. + /// + public Uri GenerateAuthenticationUri(string requestCode = null) + { + // check if request code is available + if(RequestCode == null && requestCode == null) + { + throw new APIException("Call GetRequestCode() first to receive a request_code"); + } + + // override property with given param if available + if(requestCode != null) + { + RequestCode = requestCode; + } + + return new Uri(string.Format(authentificationUri, RequestCode, Uri.EscapeDataString(CallbackUri.ToString()))); } @@ -34,18 +60,22 @@ namespace PocketSharp /// Requests the access code after authentification /// /// - public string GetAccessCode() + public string GetAccessCode(string requestCode = null) { // check if request code is available - if(RequestCode == null) + if(RequestCode == null && requestCode == null) { - throw new APIException("Authenticate the user first to receive a request_code"); + throw new APIException("Call GetRequestCode() first to receive a request_code"); } - AccessCode response = Get("oauth/authorize", new List() + // override property with given param if available + if(requestCode != null) { - new Parameter() { Name = "code", Value = RequestCode, Type = ParameterType.GetOrPost } - }); + RequestCode = requestCode; + } + + // do request + AccessCode response = Get("oauth/authorize", Utilities.CreateParamInList("code", RequestCode)); // save code to client AccessCode = response.Code; diff --git a/PocketSharp/PocketClient.cs b/PocketSharp/PocketClient.cs index d247d7d..297018a 100644 --- a/PocketSharp/PocketClient.cs +++ b/PocketSharp/PocketClient.cs @@ -17,19 +17,19 @@ namespace PocketSharp protected readonly RestClient _restClient; /// - /// default base URL for the API + /// The base URL for the Pocket API /// - protected static Uri defaultBaseUrl = new Uri("https://getpocket.com/v3/"); + protected static Uri baseUri = new Uri("https://getpocket.com/v3/"); /// /// The authentification URL /// - protected static string authentificationUrl = defaultBaseUrl + "auth/authorize?request_token={0}&redirect_uri={1}"; + protected string authentificationUri = "https://getpocket.com/auth/authorize?request_token={0}&redirect_uri={1}"; /// - /// base URL for the API + /// callback URL for API calls /// - protected Uri BaseUrl { get; set; } + protected Uri CallbackUri { get; set; } /// /// Accessor for the Pocket API key @@ -56,52 +56,28 @@ namespace PocketSharp /// /// Initializes a new instance of the class. /// - /// The API key. - public PocketClient(string consumerKey) - : this(consumerKey, "", defaultBaseUrl) { } - - - /// - /// Initializes a new instance of the class. - /// - /// The API key. - /// The access code. - public PocketClient(string consumerKey, string accessCode) - : this(consumerKey, accessCode, defaultBaseUrl) { } - - - /// - /// Initializes a new instance of the class. - /// - /// The API key. - /// The base URL. - public PocketClient(string consumerKey, Uri baseUrl) - : this(consumerKey, "", baseUrl) { } - - - /// - /// Initializes a new instance of the class. - /// - /// The API key. + /// The API key /// Provide an access code if the user is already authenticated - /// The base URL. - public PocketClient(string consumerKey, string accessCode, Uri baseUrl) + /// The callback URL is called by Pocket after authentication + public PocketClient(string consumerKey, string accessCode = null, Uri callbackUri = null) { // assign public properties - BaseUrl = baseUrl; ConsumerKey = consumerKey; // assign access code if submitted - if (accessCode != "") + if (accessCode != null) { AccessCode = accessCode.ToString(); } - // initialize REST client - _restClient = new RestClient + // assign callback uri if submitted + if (callbackUri != null) { - BaseUrl = BaseUrl.ToString() - }; + CallbackUri = callbackUri; + } + + // initialize REST client + _restClient = new RestClient(baseUri.ToString()); // add default parameters to each request _restClient.AddDefaultParameter("consumer_key", ConsumerKey); diff --git a/PocketSharp/Utilities.cs b/PocketSharp/Utilities.cs index e499587..d342b2b 100644 --- a/PocketSharp/Utilities.cs +++ b/PocketSharp/Utilities.cs @@ -34,12 +34,20 @@ namespace PocketSharp /// public static Parameter CreateParam(string name, object value, ParameterType type = ParameterType.GetOrPost) { - return new Parameter() - { - Name = name, - Value = value, - Type = type - }; + return new Parameter() { Name = name, Value = value, Type = type }; + } + + + /// + /// Creates a Parameter object within a list. + /// + /// The name. + /// The value. + /// The type. + /// + public static List CreateParamInList(string name, object value, ParameterType type = ParameterType.GetOrPost) + { + return new List() { CreateParam(name, value, type) }; } diff --git a/README.md b/README.md index 8ba0b8a..a042f29 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ PocketSharp is a C#.NET class library, that integrates the [Pocket API v3](http://getpocket.com/developer). -_If you don't know Pocket, be sure to check it out [Pocket](http://getpocket.com). It's an awesome service, which lets you save articles, videos, ... in the cloud and access it from all your devices._ +_If you don't know [Pocket](http://getpocket.com), be sure to check it out. It's an awesome service, which lets you save articles, videos, ... in the cloud and access it from all your devices._ PocketSharp consists of 4 parts: @@ -50,20 +50,26 @@ Which will output: ## Create an instance -There are 4 overloads for `PocketClient`: +Constructor: ```csharp -// used for authentication, when no accessCode is available yet -PocketClient(string consumerKey) +PocketClient(string consumerKey, string accessCode = null, Uri callbackUri = null) +``` -// start the PocketClient with an accessCode -PocketClient(string consumerKey, string accessCode) +`consumerKey`: The API key +
+`accessCode`: Provide an access code if the user is already authenticated +
+`callbackUri`: The callback URL is called by Pocket after authentication -// different base URL -PocketClient(string consumerKey, Uri baseUrl) +Example: -// accessCode and different base URL -PocketClient(string consumerKey, string accessCode, Uri baseUrl) +```csharp +PocketClient _client = new PocketClient( + consumerKey: "123498237423498723498723", + callbackUri: new Uri("http://ceecore.com"), + accessCode: "097809-oi987-izi8-jk98-oiuu89" +); ``` You can change the _Access Code_ after initialization: @@ -72,46 +78,35 @@ You can change the _Access Code_ after initialization: _client.AccessCode = "[YOU_ACCESS_CODE]"; ``` +**Before authentication** you will need to provide the `callbackUri` for authentication requests. +
+**After authentication** you will need to provide the `accessCode`. + ## Authentication In order to communicate with a Pocket User, you will need a consumer key (which is generated by [creating a new application on Pocket](http://getpocket.com/developer/apps/)) and an **Access Code**. This is a 3-step process: -1) Receive the authentication URI from the library by calling `Uri Authenticate(Uri callbackUri)`: +1) Receive the **request code** and **authentication URI** from the library by calling `string GetRequestCode()`: ```csharp -Uri authenticationUri = client.Authenticate(new Uri("http://example.com")); +string requestCode = _client.GetRequestCode(); +Uri authenticationUri = _client.GenerateAuthenticationUri(); ``` -The `callbackUri` is the URI which is triggered after the user successfully (or not) authenticated your application. - -In this step not only the `authenticationUri` is generated, but the PocketSharp client also stores a received _Request Code_ internally. +The _request code_ is stored internally, but you can also provide it as param in `GenerateAuthenticationUri(string requestCode = null)`. 2) Next you need to redirect the user to the `authenticationUri`, which displays a prompt to grant permissions for the application. After the user granted or denied, he/she is redirected to the `callbackUri`. -3) Call `string GetAccessCode()` +3) Call `string GetAccessCode(string requestCode = null)` ```csharp -string accessCode = GetAccessCode(); +string accessCode = _client.GetAccessCode(); ``` -Again, the received _Access Code_ is stored internally. -Note that `GetAccessCode` can only be called with an existing _Request Code_. If you need to re-authenticate a user, start again with Step 1). - -#### Note - -If you need to re-instantiate PocketClient after the redirect, please provide the _Request Code_: - -```csharp -_client.RequestCode = "[YOU_REQUEST_CODE]"; -``` - -After Step 1) you have public access to the RequestCode property and can store it for later usage. - -```csharp -string requestCode = _client.RequestCode; -``` +Again, the received _access code_ is stored internally. +Note that `GetAccessCode` can only be called with an existing _request code_. If you need to re-authenticate a user, start again with Step 1). #### Important @@ -233,6 +228,7 @@ Renames a tag for the specified item: ## Release History +- 2013-07-01 v0.3.0-pre update authentication process _(breaking)_ - 2013-06-27 v0.2.0 add, modify item & modify tags - 2013-06-26 v0.1.0 authentication & retrieve functionality