1 line
8.1 KiB
JSON
1 line
8.1 KiB
JSON
{"name":"PocketSharp","tagline":"C# assembly for accessing the pocket API","body":"# PocketSharp\r\n\r\n> This project is work in progress.\r\n> PocketSharp will be released as a NuGet package when ready.\r\n\r\n**PocketSharp** is a C#.NET class library, that integrates the [Pocket API v3](http://getpocket.com/developer) and consists of 4 parts:\r\n\r\n- Authentication\r\n- Retrieve\r\n- Modify\r\n- Add\r\n\r\n---\r\n\r\n_If you don't know [Pocket](http://getpocket.com), be sure to check it out. It's an awesome service that lets you save articles, videos, ... in the cloud and access it from all your devices._\r\n\r\n---\r\n\r\n## Usage Example\r\n\r\nRequest a [Consumer Key on Pocket.](http://getpocket.com/developer/apps/)\r\n\r\nInclude the PocketSharp namespace and it's associated models (you will need them later):\r\n\r\n```csharp\r\nusing PocketSharp;\r\nusing PocketSharp.Models;\r\n```\r\n\r\nInitialize PocketClient with:\r\n\r\n```csharp\r\nPocketClient _client = new PocketClient(\"[YOUR_CONSUMER_KEY]\", \"[YOUR_ACCESS_CODE]\");\r\n```\r\n\r\nDo a simple request - e.g. a search for `CSS`:\r\n\r\n```csharp\r\n_client.Search(\"css\").ForEach(\r\n\titem => Console.WriteLine(item.ID + \" | \" + item.Title)\r\n);\r\n```\r\n\r\nWhich will output:\r\n\r\n 330361896 | CSS Front-end Frameworks with comparison : By usabli.ca\r\n 345541438 | Editr - HTML, CSS, JavaScript playground\r\n 251743431 | CSS Architecture\r\n 343693149 | CSS3 Transitions - Thank God We Have A Specification!\r\n\t...\r\n\r\n## Create an instance\r\n\r\nConstructor:\r\n\r\n```csharp\r\nPocketClient(string consumerKey, string accessCode = null, Uri callbackUri = null)\r\n```\r\n\r\n`consumerKey`: The API key\r\n<br>\r\n`accessCode`: Provide an access code if the user is already authenticated\r\n<br>\r\n`callbackUri`: The callback URL is called by Pocket after authentication\r\n\r\nExample:\r\n\r\n```csharp\r\nPocketClient _client = new PocketClient(\r\n\tconsumerKey: \"123498237423498723498723\",\r\n\tcallbackUri: new Uri(\"http://ceecore.com\"),\r\n\taccessCode: \"097809-oi987-izi8-jk98-oiuu89\"\r\n);\r\n```\r\n\r\nYou can change the _Access Code_ after initialization:\r\n\r\n```csharp\r\n_client.AccessCode = \"[YOU_ACCESS_CODE]\";\r\n```\r\n\r\n**Before authentication** you will need to provide the `callbackUri` for authentication requests.\r\n<br>\r\n**After authentication** you will need to provide the `accessCode`.\r\n\r\n## Authentication\r\n\r\nIn 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**.\r\n\r\nThe authentication is a 3-step process:\r\n\r\n#### 1) Generate authentication URI\r\n\r\nReceive the **request code** and **authentication URI** from the library by calling `string GetRequestCode()`:\r\n\r\n```csharp\r\nstring requestCode = _client.GetRequestCode();\r\n// 0f453f2d-1605-8584-28fd-39af8e\r\nUri authenticationUri = _client.GenerateAuthenticationUri();\r\n// https://getpocket.com/auth/authorize?request_token=0f453f2d-1605-8584-28fd-39af8e&redirect_uri=http%253a%252f%252fceecore.com\r\n```\r\n\r\nThe _request code_ is stored internally, but you can also provide it as param in `GenerateAuthenticationUri(string requestCode = null)`.\r\n\r\n#### 2) Redirect to Pocket\r\nNext you need to redirect the user to the `authenticationUri`, which displays a prompt to grant permissions for the application (see image). After the user granted or denied, he/she is redirected to the `callbackUri`.\r\n\r\n\r\n\r\n#### 3) Get Access Code\r\nCall `string GetAccessCode(string requestCode = null)`\r\n\r\n```csharp\r\nstring accessCode = _client.GetAccessCode();\r\n// fa8bfc16-69b3-4d22-7db7-84a58d\r\n```\r\n\r\nAgain, the received _access code_ is stored internally.\r\nNote that `GetAccessCode` can only be called with an existing _request code_. If you need to re-authenticate a user, start again with Step 1).\r\n\r\n#### Important\r\n\r\n**Be sure to permanently store the _Access Code_ for your user.**\r\n<br>\r\nWithout it you would always have to redo the authentication process.\r\n\r\n## Retrieve\r\n\r\nGet list of all items:\r\n\r\n```csharp\r\nList<PocketItem> items = _client.Retrieve();\r\n// equivalent to: _client.Retrieve(RetrieveFilter.All)\r\n```\r\n\r\nFind items by a tag:\r\n\r\n```csharp\r\nList<PocketItem> items = _client.SearchByTag(\"tutorial\");\r\n```\r\n\r\nFind items by a search string:\r\n\r\n```csharp\r\nList<PocketItem> items = _client.Search(\"css\");\r\n```\r\n\r\nFind items by a filter:\r\n\r\n```csharp\r\nList<PocketItem> items = _client.Retrieve(RetrieveFilter.Favorite); // only favorites\r\n```\r\n\r\nThe RetrieveFilter Enum is specified as follows:\r\n\r\n```csharp\r\nenum RetrieveFilter { All, Unread, Archive, Favorite, Article, Video, Image }\r\n```\r\n\r\n#### Custom Parameters\r\n\r\nYou can create a completely custom parameter list for retrieval with the POCO `RetrieveParameters`:\r\n\r\n```csharp\r\nvar parameters = new RetrieveParameters()\r\n{\r\n\tCount = 50,\r\n\tOffset = 100,\r\n\tSort = SortEnum.oldest\r\n\t...\r\n};\r\n\r\nList<PocketItem> items = _client.Retrieve(parameters);\r\n```\r\n\r\n## Add\r\n\r\nAdds a new item to your pocket list.\r\nAccepts four parameters, with `uri` being required.\r\n\r\n```csharp\r\nPocketItem Add(Uri uri, string[] tags = null, string title = null, string tweetID = null)\r\n```\r\n\r\nExample:\r\n\r\n```csharp\r\nPocketItem newItem = _client.Add(\r\n\tnew Uri(\"http://www.neowin.net/news/full-build-2013-conference-sessions-listing-revealed\"),\r\n\tnew string[] { \"microsoft\", \"neowin\", \"build\" }\r\n);\r\n```\r\n\r\nThe title can be included for cases where an item does not have a title, which is typical for image or PDF URLs. If Pocket detects a title from the content of the page, this parameter will be ignored.\r\n\r\nIf you are adding Pocket support to a Twitter client, please send along a reference to the tweet status id (with the tweetID). This allows Pocket to show the original tweet alongside the article.\r\n\r\n## Modify\r\n\r\nAll Modify methods accept either the itemID (as int) or a `PocketItem` as parameter.\r\n\r\nArchive the specified item:\r\n\r\n\tbool isSuccess = _client.Archive(myPocketItem);\r\n\r\nUn-archive the specified item:\r\n\r\n\tbool isSuccess = _client.Unarchive(myPocketItem);\r\n\r\nFavorites the specified item:\r\n\r\n\tbool isSuccess = _client.Favorite(myPocketItem);\r\n\r\nUn-favorites the specified item:\r\n\r\n\tbool isSuccess = _client.Unfavorite(myPocketItem);\r\n\r\nDeletes the specified item:\r\n\r\n\tbool isSuccess = _client.Delete(myPocketItem);\r\n\r\n#### Modify tags\r\n\r\nAdd tags to the specified item:\r\n\r\n\tbool isSuccess = _client.AddTags(myPocketItem, new string[] { \"css\", \"2013\" });\r\n\r\nRemove tags from the specified item:\r\n\r\n\tbool isSuccess = _client.RemoveTags(myPocketItem, new string[] { \"css\", \"2013\" });\r\n\r\nRemove all tags from the specified item:\r\n\r\n\tbool isSuccess = _client.RemoveTags(myPocketItem);\r\n\r\nReplaces all existing tags with new ones for the specified item:\r\n\r\n\tbool isSuccess = _client.ReplaceTags(myPocketItem, new string[] { \"css\", \"2013\" });\r\n\r\nRenames a tag for the specified item:\r\n\r\n\tbool isSuccess = _client.RenameTag(myPocketItem, \"oldTagName\", \"newTagName\");\r\n\r\n---\r\n\r\n## Release History\r\n\r\n- 2013-07-07 v0.3.1 authentication fixes\r\n- 2013-07-02 v0.3.0 update authentication process \r\n- 2013-06-27 v0.2.0 add, modify item & modify tags\r\n- 2013-06-26 v0.1.0 authentication & retrieve functionality\r\n\r\n## Used Packages\r\n\r\n- [RestSharp](http://restsharp.org/)\r\n- [ServiceStack.Text](https://github.com/ServiceStack/ServiceStack.Text)\r\n\r\n## Contributors\r\n| [](http://twitter.com/artistandsocial \"Follow @artistandsocial on Twitter\") |\r\n|---|\r\n| [Tobias Klika @ceee](https://github.com/ceee) |","google":"","note":"Don't delete this file! It's used internally to help with page regeneration."} |