app/views/documentation/api.html.haml
- title "How to use the API"
%h1= title
%p The API allows you to programatically retrieve data from any public scraper using an SQL query. It's all pretty easy.
%pre
%code
GET #{api_url_in_html(content_tag(:em, '[scraper]'), content_tag(:em, '[format]'), content_tag(:em, '[api_key]'), content_tag(:em, '[sql]'), '')}
%p.alert.alert-info.download-privacy-notice
Your API calls will be shown as downloads on the scraper page.
= link_to "Why?", documentation_index_path(anchor: "open-downloads"), title: "Read about why downloader information is public and open."
%h2 Parameters
-# TODO: Write this whole form in a more concise way using the magic of simple_form
= simple_form_for @scraper, html: { class: "form-horizontal" } do
.string.input.optional.stringish.form-group#scraper-full-name-input
%label.control-label.col-sm-1{ for: "scraper-full-name" } [scraper]
.col-sm-5
%input.form-control#scraper-full-name{ maxlength: "255", name: "scraper[full_name]", type: "text", value: @scraper.full_name }
%span.help-block The full name of the scraper as seen in the url
.string.input.optional.stringish.form-group#query-input
%label.control-label.col-sm-1{ for: "query" } [sql]
.col-sm-5
%input.form-control#query{ maxlength: "255", name: "query", type: "text", value: @query }
%span.help-block
The SQL query to perform on the scraper data.
Ensure it is #{link_to 'url encoded', 'https://en.wikipedia.org/wiki/Percent-encoding'}.
.string.input.optional.stringish.form-group#format-input
%label.control-label.col-sm-1{ for: "format" } [format]
.col-sm-3
%select.form-control#format{ name: "format" }
= options_for_select(%w[json csv atom])
%span.help-block
Format of outputted data
.string.input.optional.stringish.form-group#callback-input
%label.control-label.col-sm-1{ for: "callback" } [callback]
.col-sm-5
%input.form-control#callback{ maxlength: "255", name: "query", type: "text" }
%span.help-block
(Optional) To return JSONP set "callback" to the name of your javascript callback function.
#atom-notes
%p
%strong
A note on atom feeds
%p
If you are returning an atom feed, you must configure your SQL query to return a <code>title</code>,
<code>content</code>, <code>link</code> and <code>date</code>.
%p
To make it easier, you can specify mappings below, and this will update your query above. You can link
fields together with the double pipe (<code>||</code>) operator.
.string.input.optional.stringish.form-group#title-input
%label.control-label.col-sm-1{ for: "title" } title
.col-sm-5
%input.form-control#title{ maxlength: "255", name: "title", type: "text" }
.string.input.optional.stringish.form-group#content-input
%label.control-label.col-sm-1{ for: "content" } content
.col-sm-5
%input.form-control#content{ maxlength: "255", name: "content", type: "text" }
.string.input.optional.stringish.form-group#link-input
%label.control-label.col-sm-1{ for: "link" } link
.col-sm-5
%input.form-control#link{ maxlength: "255", name: "link", type: "text" }
.string.input.optional.stringish.form-group#date-input
%label.control-label.col-sm-1{ for: "date" } date
.col-sm-5
%input.form-control#date{ maxlength: "255", name: "date", type: "text" }
.row
.col-sm-6
.string.input.optional.stringish.form-group#api-key-input
%label.control-label.col-sm-2{ for: "api-key" } [api_key]
.col-sm-10
- if current_user
%p.form-control-static#api-key= current_user.api_key
%span.help-block
Don't tell anyone else what the api key is
- else
%p= button_link_to "sign in with GitHub", user_github_omniauth_authorize_path
%h2 Example
%p
To do the API query with the values above
%div
%ul.nav.nav-tabs{ role: "tablist" }
%li.active{ role: "presentation" }
= link_to "#example-curl", "aria-controls" => "#examples-curl", role: "tab", "data-toggle" => "tab" do
Curl
%li{ role: "presentation" }
= link_to "#example-ruby", "aria-controls" => "#example-ruby", role: "tab", "data-toggle" => "tab" do
= language_name_with_icon(:ruby, size: "18x18")
%li{ role: "presentation" }
= link_to "#example-python", "aria-controls" => "#example-python", role: "tab", "data-toggle" => "tab" do
= language_name_with_icon(:python, size: "18x18")
%li{ role: "presentation" }
= link_to "#example-javascript", "aria-controls" => "#example-javascript", role: "tab", "data-toggle" => "tab" do
= image_tag("languages/javascript.png", size: "18x18")
Javascript
%li{ role: "presentation" }
= link_to "#example-php", "aria-controls" => "#example-php", role: "tab", "data-toggle" => "tab" do
= image_tag("languages/php.png", size: "18x18")
PHP
.tab-content
.tab-pane.active{ role: "tabpanel", id: "example-curl" }
= render "documentation/api_examples/curl", scraper: @scraper, query: @query
.tab-pane{ role: "tabpanel", id: "example-ruby" }
= render "documentation/api_examples/ruby", scraper: @scraper, query: @query
.tab-pane{ role: "tabpanel", id: "example-python" }
= render "documentation/api_examples/python", scraper: @scraper, query: @query
.tab-pane{ role: "tabpanel", id: "example-javascript" }
= render "documentation/api_examples/javascript", scraper: @scraper, query: @query
.tab-pane{ role: "tabpanel", id: "example-php" }
= render "documentation/api_examples/php", scraper: @scraper, query: @query
:javascript
$(function() {
var selects = {};
function update_link_url() {
$("#api_link").attr("href", $("#api_link").text());
}
function update_full_name() {
$("pre span.full_name").html($("#scraper-full-name").val());
update_link_url();
}
function update_query() {
$("pre span.unescaped-query").html($("#query").val());
$("pre span.query").html(encodeURIComponent($("#query").val()));
update_link_url();
}
function update_format() {
var format = $("#format").val();
$("pre span.format").html(format);
update_link_url();
if (format == "json") {
if (!(typeof save_callback === 'undefined')) {
$("#callback").val(save_callback);
update_callback();
}
$("#callback-input").show("fast");
}
else {
$("#callback-input").hide("fast");
save_callback = $("#callback").val();
$("#callback").val("");
update_callback();
}
if (format == "atom") {
$("#atom-notes").show("fast");
} else {
$("#atom-notes").hide("fast");
}
}
function update_callback() {
var v = $("#callback").val();
if (v == "") {
$("pre span.callback").html("");
}
else {
$("pre span.callback").html("&callback=" + v);
}
update_link_url();
}
function update_atom_query(string) {
var v = $(this).val();
var n = $(this).attr('name');
if(v == "")
selects[n] = null;
else
selects[n] = v + " as " + n;
query = $("#query").val();
queryItems = $.map(selects, function (value, key) { return value; });
var selectString = (queryItems.length == 0) ? "*" : queryItems.join(", ");
newQuery = query.replace(/select (.+) from/i, "select " + selectString + " from");
$("#query").val(newQuery);
update_query();
}
update_full_name();
update_query();
update_format();
update_callback();
$("#scraper-full-name").change(update_full_name).keyup(update_full_name);
$("#query").change(update_query).keyup(update_query);
$("#format").change(update_format);
$("#callback").change(update_callback).keyup(update_callback);
$("#title").change(update_atom_query).keyup(update_atom_query);
$("#content").change(update_atom_query).keyup(update_atom_query);
$("#link").change(update_atom_query).keyup(update_atom_query);
$("#date").change(update_atom_query).keyup(update_atom_query);
});