add first version of documentation;
This commit is contained in:
@@ -30,7 +30,7 @@ namespace PocketSharp
|
||||
/// <summary>
|
||||
/// base URL for the API
|
||||
/// </summary>
|
||||
public Uri BaseUrl { get; set; }
|
||||
protected Uri BaseUrl { get; set; }
|
||||
|
||||
/// <summary>
|
||||
/// Accessor for the Pocket API key
|
||||
@@ -46,7 +46,7 @@ namespace PocketSharp
|
||||
/// <summary>
|
||||
/// Code retrieved on authentification
|
||||
/// </summary>
|
||||
protected string RequestCode { get; set; }
|
||||
public string RequestCode { get; set; }
|
||||
|
||||
/// <summary>
|
||||
/// Code retrieved on authentification-success
|
||||
|
||||
@@ -1,12 +1,145 @@
|
||||
#PocketSharp
|
||||
# PocketSharp
|
||||
|
||||
**NOTE**: This is work in progress and cannot be used yet. I will update the readme and generate a documentation on first release.
|
||||
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._
|
||||
|
||||
PocketSharp consists of 4 parts:
|
||||
|
||||
- Authentication
|
||||
- Retrieve
|
||||
- Modify _(work in progress)_
|
||||
- Add _(work in progress)_
|
||||
|
||||
---
|
||||
|
||||
PocketSharp provides easy access to the [Pocket API](http://getpocket.com/developer).
|
||||
## Usage Example
|
||||
|
||||
_Check out [Pocket](http://getpocket.com), it's an awesome service, which lets you save articles videos, ... into the cloud and access it from all your devices._
|
||||
Request a Consumer Key on Pocket: [My Applications on Pocket](http://getpocket.com/developer/apps/)
|
||||
|
||||
Include the PocketSharp namespace and it's associated models (you will need them later):
|
||||
|
||||
using PocketSharp;
|
||||
using PocketSharp.Models;
|
||||
|
||||
Initialize PocketClient with:
|
||||
|
||||
PocketClient _client = new PocketClient("[YOUR_CONSUMER_KEY]", "[YOUR_ACCESS_CODE]");
|
||||
|
||||
Do a simple request - e.g. a search for `CSS`:
|
||||
|
||||
_client.Search("css").ForEach(
|
||||
item => Console.WriteLine(item.ID + " | " + item.Title)
|
||||
);
|
||||
|
||||
Which will output:
|
||||
|
||||
330361896 | CSS Front-end Frameworks with comparison : By usabli.ca
|
||||
345541438 | Editr - HTML, CSS, JavaScript playground
|
||||
251743431 | CSS Architecture
|
||||
343693149 | CSS3 Transitions - Thank God We Have A Specification!
|
||||
...
|
||||
|
||||
## Create an instance
|
||||
|
||||
There are 4 overloads for `PocketClient`:
|
||||
|
||||
// used for authentication, when no accessCode is available yet
|
||||
PocketClient(string consumerKey)
|
||||
|
||||
// start the PocketClient with an accessCode
|
||||
PocketClient(string consumerKey, string accessCode)
|
||||
|
||||
// different base URL
|
||||
PocketClient(string consumerKey, Uri baseUrl)
|
||||
|
||||
// accessCode and different base URL
|
||||
PocketClient(string consumerKey, string accessCode, Uri baseUrl)
|
||||
|
||||
You can change the _Access Code_ after initialization:
|
||||
|
||||
_client.AccessCode = "[YOU_ACCESS_CODE]";
|
||||
|
||||
## 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)`:
|
||||
|
||||
Uri authenticationUri = client.Authenticate(new Uri("http://example.com"));
|
||||
|
||||
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.
|
||||
|
||||
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()`
|
||||
|
||||
string accessCode = 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_:
|
||||
|
||||
_client.RequestCode = "[YOU_REQUEST_CODE]";
|
||||
|
||||
After Step 1) you have public access to the RequestCode property and can store it for later usage.
|
||||
|
||||
string requestCode = _client.RequestCode;
|
||||
|
||||
#### Important
|
||||
|
||||
**Be sure to permanently store the _Access Code_ for your user.**
|
||||
<br>
|
||||
Without it you would always have to redo the authentication process.
|
||||
|
||||
## Retrieve
|
||||
|
||||
Find items by a tag:
|
||||
|
||||
List<PocketItem> items = _client.SearchByTag("tutorial");
|
||||
|
||||
Find items by a search string:
|
||||
|
||||
List<PocketItem> items = _client.Search("css");
|
||||
|
||||
Find items by a filter:
|
||||
|
||||
List<PocketItem> items = _client.Retrieve(RetrieveFilter.Favorite); // only favorites
|
||||
|
||||
The RetrieveFilter Enum is specified as follows:
|
||||
|
||||
enum RetrieveFilter { All, Unread, Archive, Favorite, Article, Video, Image }
|
||||
|
||||
### Custom Parameters
|
||||
|
||||
You can create a completely custom parameter list for retrieval with the POCO `RetrieveParameters`:
|
||||
|
||||
var parameters = new RetrieveParameters()
|
||||
{
|
||||
Count = 50,
|
||||
Offset = 100,
|
||||
Sort = SortEnum.oldest
|
||||
...
|
||||
};
|
||||
|
||||
List<PocketItem> items = _client.Retrieve(parameters);
|
||||
|
||||
## Add & Modify
|
||||
|
||||
This is work in progress - don't use these methods!
|
||||
|
||||
---
|
||||
|
||||
## Release History
|
||||
|
||||
- 2013-06-26 v0.1.0 authentication & retrieve functionality
|
||||
|
||||
## Contributors
|
||||
| [](http://twitter.com/artistandsocial "Follow @artistandsocial on Twitter") |
|
||||
|
||||
Reference in New Issue
Block a user