From c52742cb7c587ed7486686e8ddbe2c4fe51e4365 Mon Sep 17 00:00:00 2001
From: Seb Bacon <seb.bacon@gmail.com>
Date: Fri, 25 Feb 2011 18:36:23 +0000
Subject: various help files that would normally need to be localised

---
 lib/views/help/api.rhtml | 82 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 lib/views/help/api.rhtml

(limited to 'lib/views/help/api.rhtml')

diff --git a/lib/views/help/api.rhtml b/lib/views/help/api.rhtml
new file mode 100644
index 0000000..6f27cf9
--- /dev/null
+++ b/lib/views/help/api.rhtml
@@ -0,0 +1,82 @@
+<% @title = "Application Programming Interface - API" %>
+
+<%= render :partial => 'sidebar' %>
+
+<h1><%=@title %></h1>
+
+<h2> Introduction </h2>
+
+<p>This page explains how programmers can make other websites and software
+interact with WhatDoTheyKnow via an "API".
+</p>
+
+<p>WhatDoTheyKnow does not have a full API yet, but we are gradually adding
+lots of things that are similar in use to an API as they are requested.
+</p>
+
+<hr>
+
+<h2> 1. Linking to new requests </h2>
+
+<p>To encourage your users to make links to a particular public authority, use URLs of the form
+<%= link_to new_request_to_body_url(:url_name => "liverpool_city_council") , new_request_to_body_url(:url_name => "liverpool_city_council") %>. 
+These are the parameters you can add to those URLs, either in the URL or from a form.
+
+<ul>
+    <li> <strong>title</strong> - default summary of the new request.</li>
+    <li> <strong>default_letter</strong> - default text of the body of the letter. The salutation (Dear...) and signoff (Yours...) are wrapped round this. </li>
+    <li> <strong>body</strong> - as an alternative to default_letter, this sets the default entire text of the request, so you can customise the salutation and signoff. </li>
+    <li> <strong>tags</strong> - space separated list of tags, so you can find and link up any requests made later, e.g. <em>openlylocal spending_id:12345</em>. The : indicates it is a machine tag. The values of machine tags may also include colons, useful for URIs.
+</ul>
+
+<hr>
+
+<h2> 2. RSS (actually, Atom) feeds </h2>
+
+<p>There are Atom feeds on most pages which list FOI requests, which you can
+use to get updates and links in XML format. Find the URL of the Atom feed in
+one of these ways: 
+<ul>
+    <li>Look for the <img src="/images/feed-16.png" alt=""> RSS feed links.</li>
+    <li>Examine the <tt>&lt;link rel="alternate" type="application/atom+xml"&gt;</tt> tag in the head of the HTML. </li>
+    <li>Add <tt>/feed</tt> to the start of another URL.
+</ul>
+
+<p>In particular, even complicated search queries have Atom feeds.
+You can do all sorts of things with them, such as query by authority, by file
+type, by date range, or by status. See the <a href="/search">advanced search
+tips</a> for details.
+
+<hr>
+
+<h2> 3. JSON structured data </h2>
+
+<p>Quite a few pages have JSON versions, which let you download information about
+objects in a structured form. Find them by:
+<ul>
+    <li>Adding <tt>.json</tt> to the end of the URL. </li>
+    <li>Look for the <tt>&lt;link rel="alternate" type="application/json"&gt;</tt> tag in the head of the HTML. </li>
+</ul>
+</p>
+
+<p>Requests, users and authorities all have JSON versions containing basic
+information about them. Every Atom feed has a JSON equivalent, containing
+information about the list of events in the feed.
+</p>
+
+<hr>
+<h2> 4. Spreadsheet of all authorities </h2>
+
+<p>
+A spreadsheet file listing every body in WhatDoTheyKnow is available:
+<%= link_to "all-authorities.csv", all_public_bodies_csv_url() %>
+</p>
+
+<hr>
+
+<p>Please <a href="/help/contact">contact us</a> if you need an API feature that isn't there yet. It's
+very much a work in progress, and we do add things when people ask us to.</p>
+
+<div id="hash_link_padding"></div>
+
+
-- 
cgit v1.2.3