Charlie Harvey

Charlie Harvey REST Content API Documentation

There is an API of sorts for my site content. It uses REST to provide read access to the site content, which is all fine to use under Creative Commons BY-NC-SA. Open data and all that. You don’t need a key to use it or any of that bullshit. But I would love to hear what you do with it if you do.

For people who don’t need no stinking API I also provide RSS and Atom feeds of much of the site content.

Usage

The API is a standard REST-type of a setup, but in a different namespace to the normal site HTML.

The data are returned as JSON by default, but you can modify the Accept header to receive XML or YAML if that’s your bag. No other formats are supported.

The following code examples illustrate how the API is used. The responses are truncated for brevity

Code examples

API endpoints

In the following documentation, parameters to API calls are shown in square brackets like this: [id]

Pages

The content under the blog section of the website is referred to as pages by the API

Recent pages

Retrieve the 10 most recently published pages $ curl http://openstats.charlieharvey.org.uk/page/api/recent Resulting in JSON like this { "pages" : [ { "link" : "http://beta.charlieharvey.org.uk:3000/page/2013_reading_roundup", "author" : "Charlie Harvey", "parent_id" : "257", "created_at" : "2013-12-23", "summary" : "Last year I did a rundown of the books I read in 2012, mostly as I wanted to play with infogr.am. But also, let’s face it, because my propensity to navel-gaze craves occasional indulgence. This year I repeat the experiment in a yearly roundup of my reading habits… Reading stat", "slug" : "2013_reading_roundup", "id" : "316", "title" : "2013: My favourite books and reading stats" }, … ] }

Single page by [id]

Retrieve the page with id [id] $ curl http://openstats.charlieharvey.org.uk/page/api/1 Resulting in JSON like this { "page" : { "link" : "http://beta.charlieharvey.org.uk:3000/page/index", "author" : "Charlie Harvey", "parent_id" : "0", "created_at" : "2005-11-09", "summary" : "These pages contain bits of html, perl, sysadminning, activism, politics and that for your perusal…", "slug" : "index", "id" : "1", "title" : "Blog" } }

Social

All social

Return two lists — one of my 10 most recent tweets and one of my 10 most recent scrobbles $ curl http://openstats.charlieharvey.org.uk/social/api/all Resulting in JSON like this { "tweets" : [ { "link" : "https://twitter.com/ciderpunx/status/417563169138044928", "title" : "<a href=\"http://search.twitter.com/search?q=%23security\">#security</a> New Fund to Support Snowden-like Whistleblowers: HAMBURG – A new foundation to support wh... <a href=\"http://wrd.cm/19wQVkG\">http://wrd.cm/19wQVkG</a>  ♺ <a href=\"http://twitter.com/wired\">@wired</a>" }, { "link" : "https://twitter.com/ciderpunx/status/417450940824694784", "title" : "<a href=\"http://search.twitter.com/search?q=%23security\">#security</a> WikiLeaks’ Assange: Sysadmins of the World, Unite!: HAMBURG – Faced with increasing encro... <a href=\"http://wrd.cm/19z3kYz\">http://wrd.cm/19z3kYz</a>  ♺ <a href=\"http://twitter.com/wired\">@wired</a>" }, … ], "scrobbles" : [ { "link" : "http://www.last.fm/music/Johann+Sebastian+Bach/_/Orchestral+Suite+No.1+in+C,BWV", "title" : "Johann Sebastian Bach – Orchestral Suite No.1 in C,BWV" }, { "link" : "http://www.last.fm/music/Johann+Sebastian+Bach/_/Orchestral+Suite+No.1+in+C,BWV", "title" : "Johann Sebastian Bach – Orchestral Suite No.1 in C,BWV" }, … ] }

Scrobbles

Return a list of my 10 most recent scrobbles $ curl http://openstats.charlieharvey.org.uk/social/api/scrobbles Resulting in JSON like this { "scrobbles" : [ { "link" : "http://www.last.fm/music/Johann+Sebastian+Bach/_/Orchestral+Suite+No.1+in+C,BWV", "title" : "Johann Sebastian Bach – Orchestral Suite No.1 in C,BWV" }, { "link" : "http://www.last.fm/music/Johann+Sebastian+Bach/_/Orchestral+Suite+No.1+in+C,BWV", "title" : "Johann Sebastian Bach – Orchestral Suite No.1 in C,BWV" }, … ] }

Tweets

Return a list of my 10 most recent tweets $ curl http://openstats.charlieharvey.org.uk/social/api/tweets Resulting in JSON like this { "tweets" : [ { "link" : "https://twitter.com/ciderpunx/status/417563169138044928", "title" : "<a href=\"http://search.twitter.com/search?q=%23security\">#security</a> New Fund to Support Snowden-like Whistleblowers: HAMBURG – A new foundation to support wh... <a href=\"http://wrd.cm/19wQVkG\">http://wrd.cm/19wQVkG</a>  ♺ <a href=\"http://twitter.com/wired\">@wired</a>" }, { "link" : "https://twitter.com/ciderpunx/status/417450940824694784", "title" : "<a href=\"http://search.twitter.com/search?q=%23security\">#security</a> WikiLeaks’ Assange: Sysadmins of the World, Unite!: HAMBURG – Faced with increasing encro... <a href=\"http://wrd.cm/19z3kYz\">http://wrd.cm/19z3kYz</a>  ♺ <a href=\"http://twitter.com/wired\">@wired</a>" }, … ] }

Files

Recent files

Return a list of my 10 most recent files $ curl http://openstats.charlieharvey.org.uk/file/api/recent Resulting in JSON like this { "files" : [ { "body" : "<p>Twitter recently got rid of the ability to get search results as an RSS as part of their API update of 11 June 2013.</p> <p>I found those feeds rather useful, so I made a little screen scraper that reimplements the functionality without needing to auth against their API (it just pulls the results out of the web search page). I guess this will be good for a while longer, like enough time to switch to <a href=\"http://status.net/\">statusnet</a>, identica, or whatever.</p><p>It might be of use to some others in the monastry and illustrates the power of <a href=\"http://search.cpan.org/~mirod/HTML-TreeBuilder-XPath-0.14/lib/HTML/TreeBuilder/XPath.pm\">HTML::TreeBuilder::XPath</a>.</p>", "link" : "http://beta.charlieharvey.org.uk:3000/file/uid/111", "created_at" : "2013-06-17", "author" : "Charlie Harvey", "category" : "culture", "id" : "111", "title" : "tweetsearch_to_rss.pl: Get twitter searches as an RSS feed with perl" }, … ] }

Recent files in [category]

Return a list of the 10 most recent files in a category $ curl http://openstats.charlieharvey.org.uk/file/api/culture/recent Resulting in JSON like this { "files" : [ { "body" : "<p>Twitter recently got rid of the ability to get search results as an RSS as part of their API update of 11 June 2013.</p> \r\n\r\n<p>I found those feeds rather useful, so I made a little screen scraper that reimplements the functionality without needing to auth against their API (it just pulls the results out of the web search page). I guess this will be good for a while longer, like enough time to switch to <a href=\"http://status.net/\">statusnet</a>, identica, or whatever.</p>\r\n\r\n<p>It might be of use to some others in the monastry and illustrates the power of <a href=\"http://search.cpan.org/~mirod/HTML-TreeBuilder-XPath-0.14/lib/HTML/TreeBuilder/XPath.pm\">HTML::TreeBuilder::XPath</a>.</p>", "link" : "http://beta.charlieharvey.org.uk:3000/file/uid/111", "created_at" : "2013-06-17", "author" : "Charlie Harvey", "category" : "culture", "id" : "111", "title" : "tweetsearch_to_rss.pl: Get twitter searches as an RSS feed with perl" }, … ] }

Details of file by [id]

Return the details of file id [id] $ curl http://openstats.charlieharvey.org.uk/file/api/[id] Resulting in JSON like this { "file" : { "body" : "<p>Twitter recently got rid of the ability to get search results as an RSS as part of their API update of 11 June 2013.</p> <p>I found those feeds rather useful, so I made a little screen scraper that reimplements the functionality without needing to auth against their API (it just pulls the results out of the web search page). I guess this will be good for a while longer, like enough time to switch to <a href=\"http://status.net/\">statusnet</a>, identica, or whatever.</p><p>It might be of use to some others in the monastry and illustrates the power of <a href=\"http://search.cpan.org/~mirod/HTML-TreeBuilder-XPath-0.14/lib/HTML/TreeBuilder/XPath.pm\">HTML::TreeBuilder::XPath</a>.</p>", "link" : "http://beta.charlieharvey.org.uk:3000/file/uid/111", "created_at" : "2013-06-17", "author" : "Charlie Harvey", "category" : "culture", "id" : "111", "title" : "tweetsearch_to_rss.pl: Get twitter searches as an RSS feed with perl" } }

Comments

Return a list of the 10 most recently published comments $ curl http://openstats.charlieharvey.org.uk/comment/api/recent Resulting in JSON like this { "comments" : [ { "body" : "Ey Charlie, nice story you did a pretty good job.\r\nthanks for sharing it : )", "link" : "http://beta.charlieharvey.org.uk:3000/comment/317", "created_at" : "2013-12-19", "url" : null, "nick" : null, "id" : "317", "title" : null }, … ] }

Comment by [id]

Return the details of comment id [id] $ curl http://openstats.charlieharvey.org.uk/comment/api/111 Resulting in JSON like this { "comment" : { "link" : "http://beta.charlieharvey.org.uk:3000/comment/111", "body" : "Props to Grumpy Git for liveblogging a cider tasting in the comments thread ;-) Glad you had some cidery fun and hope you didn't get into a fight!", "created_at" : "2011-09-01", "url" : "http://charlieharvey.org.uk/page/index/", "title" : "Liveblogging", "nick" : "Charlie", "id" : "111" } }

Tags

All tags

Return a list of all tags $ curl http://openstats.charlieharvey.org.uk/tag/api Resulting in JSON like this { "tags" : [ { "link" : "http://beta.charlieharvey.org.uk:3000/tag/1in12", "id" : "400", "title" : "1in12" }, { "link" : "http://beta.charlieharvey.org.uk:3000/tag/2012", "id" : "477", "title" : "2012" }, … }

Return a list of content tagged with the tag that has id [id] $ curl http://openstats.charlieharvey.org.uk/tag/api/477 Resulting in JSON like this { "tag" : { "link" : "http://beta.charlieharvey.org.uk:3000/tag/2012", "writings" : [], "id" : "477", "title" : "2012", "pages" : [ { "link" : "http://beta.charlieharvey.org.uk:3000/page/self_indulgent_navel_gazing_about_books_i_read_in_2012", "summary" : "It is traditional — and who am I to dispute traditions? — to publish navel-gazing lists and yearly \"roundups\" at or about New Year. So, I have had a self-indulgent look back at 2012 through the lens of the books that I read and articles that I wrote this year. Gimme some stats", "updated_at" : "2012-12-30", "author" : "Charlie Harvey", "id" : "255", "title" : "2012 Reading Highlights" } ] } }

Popular

Popular for [week|month|year|all-time]

Return a list of the most popular content for the last [week|month|year] or for [all-time] $ curl http://openstats.charlieharvey.org.uk/popular/week/api Resulting in JSON like this. Note that an array of pages in order of populartiy and an associative array of page names to details are returned. The associative array may not be in order. { "page_titles_ordered" : [ "127.0.0.1", "Pages : Motherboard details from the GNU/Linux commandline", "Pages : Rooting the Coby Kyros MID9742 Android tablet", "Pages : Tool: Twitter RSS Feed Getter", "Pages : Ettercap remote_browser Plugin Fun", "Pages : Split multi-page PDFs into single page PDFs on GNU/Linux with pdftk", "Pages : Tip: Latest Chromium Browser on Debian Squeeze", "Daily Mail Story Generator", "About", "Pages : Gnome 3 Nautilus Tip — Make the Delete Key Delete Files" ], "pages" : { "Pages : Split multi-page PDFs into single page PDFs on GNU/Linux with pdftk" : { "hits" : "36", "unique_visits" : "34", "url" : "charlieharvey.org.uk/page/howto_breaking_pdfs_up_into_mutiple_pages", "title" : "Pages : Split multi-page PDFs into single page PDFs on GNU/Linux with pdftk" }, "Pages : Ettercap remote_browser Plugin Fun" : { "hits" : "46", "unique_visits" : "37", "url" : "charlieharvey.org.uk/page/ettercap_remote_browser_fun", "title" : "Pages : Ettercap remote_browser Plugin Fun" } … } }

ROT-13

ROT-13 [string_to_ROT13]

Return the ROT-13ed string of [string_to_ROT13]. Strings ought to be URL encoded. Note that ROT-13ing a string twice un-ROT-13s it. $ curl http://openstats.charlieharvey.org.uk/rot13/api/rot-13+roolz Resulting in JSON like this { "msg" : "ebg-13+ebbym" }