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
- Recent pages as JSON (default)
$ curl http://charlieharvey.org.uk/page/api/recent { "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" }, … - Recent pages as XML
$ curl -H"Accept:text/xml" http://charlieharvey.org.uk/page/api/recent <data> <pages id="316" author="Charlie Harvey" created_at="2013-12-23" link=… - Recent pages as YAML
$ curl -H"Accept:text/x-yaml" http://charlieharvey.org.uk/page/api/recent --- pages: - author: Charlie Harvey created_at: 2013-12-23 id: 316 link: … - Using jQuery to pull recent pages into an html page
<html> <head> <title>Blog example</title> <script src="//code.jquery.com/jquery-1.8.1.min.js"></script> </head> <body> <h1>Blogs from charlieharveyr.org.uk</h1> <div id="blogs"> </div> <script> (function() { var blogsAPI = "/page/api/recent"; var the_things = []; $.getJSON( blogsAPI, {}) .done(function( data ) { $.each( data.pages, function( i, page ) { the_things.push( "<li><h4><a href='" + page.link + "'>"+ page.title +"</a></h4><p>" + page.summary + "</p></li>" ); }); $( "<ul/>", { "class": "no-decoration tinytext", html: the_things.join( "" ) }).appendTo( "#blogs" ); }); })(); </script> </body> </html>
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://charlieharvey.org.uk/page/api/recentResulting 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://charlieharvey.org.uk/page/api/1Resulting 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://charlieharvey.org.uk/social/api/allResulting 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://charlieharvey.org.uk/social/api/scrobblesResulting 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://charlieharvey.org.uk/social/api/tweetsResulting 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://charlieharvey.org.uk/file/api/recentResulting 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://charlieharvey.org.uk/file/api/culture/recentResulting 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://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://charlieharvey.org.uk/comment/api/recentResulting 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://charlieharvey.org.uk/comment/api/111Resulting 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://charlieharvey.org.uk/tag/apiResulting 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://charlieharvey.org.uk/tag/api/477Resulting 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://charlieharvey.org.uk/popular/week/apiResulting 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://charlieharvey.org.uk/rot13/api/rot-13+roolzResulting in JSON like this{ "msg" : "ebg-13+ebbym" }