175 lines
4.6 KiB
Markdown
175 lines
4.6 KiB
Markdown
# PocketSharp
|
|
|
|
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)_
|
|
|
|
---
|
|
|
|
## Usage Example
|
|
|
|
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):
|
|
|
|
```csharp
|
|
using PocketSharp;
|
|
using PocketSharp.Models;
|
|
```
|
|
|
|
Initialize PocketClient with:
|
|
|
|
```csharp
|
|
PocketClient _client = new PocketClient("[YOUR_CONSUMER_KEY]", "[YOUR_ACCESS_CODE]");
|
|
```
|
|
|
|
Do a simple request - e.g. a search for `CSS`:
|
|
|
|
```csharp
|
|
_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`:
|
|
|
|
```csharp
|
|
// 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:
|
|
|
|
```csharp
|
|
_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)`:
|
|
|
|
```csharp
|
|
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()`
|
|
|
|
```csharp
|
|
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_:
|
|
|
|
```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;
|
|
```
|
|
|
|
#### 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:
|
|
|
|
```csharp
|
|
List<PocketItem> items = _client.SearchByTag("tutorial");
|
|
```
|
|
|
|
Find items by a search string:
|
|
|
|
```csharp
|
|
List<PocketItem> items = _client.Search("css");
|
|
```
|
|
|
|
Find items by a filter:
|
|
|
|
```csharp
|
|
List<PocketItem> items = _client.Retrieve(RetrieveFilter.Favorite); // only favorites
|
|
```
|
|
|
|
The RetrieveFilter Enum is specified as follows:
|
|
|
|
```csharp
|
|
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`:
|
|
|
|
```csharp
|
|
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") |
|
|
|---|
|
|
| [Tobias Klika @ceee](https://github.com/ceee) | |