update authentication process;

PocketSharp/Components/Authentification.cs

@@ -11,22 +11,48 @@ namespace PocketSharp
   public partial class PocketClient
   {
     /// <summary>
-    /// Gets the authentification URI.
+    /// Retrieves the requestCode from Pocket.
     /// </summary>
-    /// <param name="callbackUri">The callback URI.</param>
     /// <returns></returns>
-    public Uri Authenticate(Uri callbackUri)
+    public string GetRequestCode()
     {
-      RequestCode response = Get<RequestCode>("oauth/request", new List<Parameter>()
+      // 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<RequestCode>("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;
+    }
+
+
+    /// <summary>
+    /// Generate Authentication URI from requestCode
+    /// </summary>
+    /// <param name="requestCode">The requestCode.</param>
+    /// <returns></returns>
+    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
     /// </summary>
     /// <returns></returns>
-    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<AccessCode>("oauth/authorize", new List<Parameter>()
+      // 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<AccessCode>("oauth/authorize", Utilities.CreateParamInList("code", RequestCode));
 
       // save code to client
       AccessCode = response.Code;

PocketSharp/Components/ModifyTags.cs

@@ -78,7 +78,7 @@ namespace PocketSharp
 
 
     /// <summary>
-    /// Replaces the specified tags.
+    /// Replaces all existing tags with new ones.
     /// </summary>
     /// <param name="itemID">The item ID.</param>
     /// <param name="tags">The tags.</param>
@@ -90,7 +90,7 @@ namespace PocketSharp
 
 
     /// <summary>
-    /// Replaces the specified tags.
+    /// Replaces all existing tags with new ones.
     /// </summary>
     /// <param name="item">The item.</param>
     /// <param name="tags">The tags.</param>

PocketSharp/Models/Response/Add.cs

@@ -6,7 +6,7 @@ namespace PocketSharp.Models
   /// Add Response
   /// </summary>
   [DataContract]
-  class Add : ResponseBase
+  internal class Add : ResponseBase
   {
     /// <summary>
     /// Gets or sets the item.

PocketSharp/Models/Response/Modify.cs

@@ -6,7 +6,7 @@ namespace PocketSharp.Models
   /// Modify Response
   /// </summary>
   [DataContract]
-  class Modify : ResponseBase
+  internal class Modify : ResponseBase
   {
     /// <summary>
     /// Gets or sets the action results.

PocketSharp/Models/Response/ResponseBase.cs

@@ -6,7 +6,7 @@ namespace PocketSharp.Models
   /// Base for Responses
   /// </summary>
   [DataContract]
-  class ResponseBase
+  internal class ResponseBase
   {
     /// <summary>
     /// Gets or sets a value indicating whether this <see cref="ResponseBase"/> is status.

PocketSharp/Models/Response/Retrieve.cs

@@ -7,7 +7,7 @@ namespace PocketSharp.Models
   /// Item Response
   /// </summary>
   [DataContract]
-  class Retrieve : ResponseBase
+  internal class Retrieve : ResponseBase
   {
     /// <summary>
     /// Gets or sets the complete.

PocketSharp/PocketClient.cs

@@ -17,19 +17,19 @@ namespace PocketSharp
     protected readonly RestClient _restClient;
 
     /// <summary>
-    /// default base URL for the API
+    /// The base URL for the Pocket API
     /// </summary>
-    protected static Uri defaultBaseUrl = new Uri("https://getpocket.com/v3/");
+    protected static Uri baseUri = new Uri("https://getpocket.com/v3/");
 
     /// <summary>
     /// The authentification URL
     /// </summary>
-    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}";
 
     /// <summary>
-    /// base URL for the API
+    /// callback URL for API calls
     /// </summary>
-    protected Uri BaseUrl { get; set; }
+    protected Uri CallbackUri { get; set; }
 
     /// <summary>
     /// Accessor for the Pocket API key
@@ -56,52 +56,28 @@ namespace PocketSharp
     /// <summary>
     /// Initializes a new instance of the <see cref="PocketClient"/> class.
     /// </summary>
-    /// <param name="consumerKey">The API key.</param>
-    public PocketClient(string consumerKey)
-      : this(consumerKey, "", defaultBaseUrl) { }
-
-
-    /// <summary>
-    /// Initializes a new instance of the <see cref="PocketClient" /> class.
-    /// </summary>
-    /// <param name="consumerKey">The API key.</param>
-    /// <param name="accessCode">The access code.</param>
-    public PocketClient(string consumerKey, string accessCode)
-      : this(consumerKey, accessCode, defaultBaseUrl) { }
-
-
-    /// <summary>
-    /// Initializes a new instance of the <see cref="PocketClient" /> class.
-    /// </summary>
-    /// <param name="consumerKey">The API key.</param>
-    /// <param name="baseUrl">The base URL.</param>
-    public PocketClient(string consumerKey, Uri baseUrl)
-      : this(consumerKey, "", baseUrl) { }
-
-
-    /// <summary>
-    /// Initializes a new instance of the <see cref="PocketClient"/> class.
-    /// </summary>
-    /// <param name="consumerKey">The API key.</param>
+    /// <param name="consumerKey">The API key</param>
     /// <param name="accessCode">Provide an access code if the user is already authenticated</param>
-    /// <param name="baseUrl">The base URL.</param>
-    public PocketClient(string consumerKey, string accessCode, Uri baseUrl)
+    /// <param name="callbackUri">The callback URL is called by Pocket after authentication</param>
+    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);

PocketSharp/Utilities.cs

@@ -1,7 +1,7 @@
-using RestSharp;
+
+using RestSharp;
 using System;
 using System.Collections.Generic;
-
 namespace PocketSharp
 {
   /// <summary>
@@ -34,12 +34,20 @@ namespace PocketSharp
     /// <returns></returns>
     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 };
+    }
+
+
+    /// <summary>
+    /// Creates a Parameter object within a list.
+    /// </summary>
+    /// <param name="name">The name.</param>
+    /// <param name="value">The value.</param>
+    /// <param name="type">The type.</param>
+    /// <returns></returns>
+    public static List<Parameter> CreateParamInList(string name, object value, ParameterType type = ParameterType.GetOrPost)
+    {
+      return new List<Parameter>() { CreateParam(name, value, type) };
     }
 
 

README.md

@@ -1,21 +1,23 @@
 # PocketSharp
 
+> This project is work in progress. Be aware of this!
+
 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:
 
 - Authentication
 - Retrieve
-- Modify _(work in progress)_
-- Add _(work in progress)_
+- Modify
+- Add
 
 ---
 
 ## Usage Example
 
-Request a Consumer Key on Pocket: [My Applications on Pocket](http://getpocket.com/developer/apps/)
+Request a [Consumer Key on Pocket.](http://getpocket.com/developer/apps/)
 
 Include the PocketSharp namespace and it's associated models (you will need them later):
 
@@ -48,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
+<br>
+`accessCode`: Provide an access code if the user is already authenticated
+<br>
+`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:
@@ -70,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.
+<br>
+**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
 
@@ -205,6 +202,8 @@ Deletes the specified item:
 
 	bool isSuccess = _client.Delete(myPocketItem);
 
+#### Modify tags
+
 Add tags to the specified item:
 
 	bool isSuccess = _client.AddTags(myPocketItem, new string[] { "css", "2013" });
@@ -229,6 +228,8 @@ 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
 
 ## Contributors