regluit/api/templates/api_help.html

{% extends 'basedocumentation.html' %}

{% block title %}API Help{% endblock %}

{% block doccontent %}

    <h2>API Help</h2>
    <p>Some of the data from Unglue.it is avaiable via a JSON API. You will need a key and username to be able to use the API.
    </p>
    {% if user.is_authenticated %}
       <p> Welcome {{user.username}}. Your API key is <span style="font-weight:bold">{{api_key}}</span>.</p>
    {% else %}
       <p> Please <a href="{% url 'superlogin' %}?next={% firstof request.get_full_path|urlencode '/' %}"><span>sign in</span></a> first.</p>
    {% endif %}
    <h3>Ebook Widgets</h3>
    <p>You don't need an API key to embed Ebook (HTML) widgets. </p>
    <div>Here's a widget that displays Unglue.it's featured ebook - it changes most every day!  <a href="{% url 'widget' 'featured' %}">{{base_url}}{% url 'widget' 'featured' %}</a>. Copy/paste this into your site:<br /><textarea rows="7" cols="22">&lt;iframe src="{{base_url}}/api/widget/featured/" width="152" height="325" frameborder="0"&gt;&lt;/iframe&gt;</textarea>
       <iframe src="{{base_url}}{% url 'widget' 'featured' %}" width="152" height="325" frameborder="0"></iframe>
    </div>
    <div>If your website doesn't allow javascript (wordpress blogs, for example) you can use the no-script version. Copy/paste this into your site:<br /><textarea rows="7" cols="22">&lt;div style="font-size:12px; width:120px; line-height:16px; padding:5px; height:220px; background-color:#fff; color:#3d4e53; border:5px solid #edf3f4;"&gt;
    &lt;a href="{{base_url}}{% url 'featured_url' %}"&gt;
&lt;img width="120" height="182" src="{{base_url}}{% url 'featured_cover' %}" alt="unglue.it featured book" /&gt;
&lt;/a&gt;&lt;/div&gt;</textarea>
<div style="display:inline-block;width: 153px;">
<div style="font-size:12px; width:120px; line-height:16px; padding:5px; height:220px; background-color:#fff; color:#3d4e53; border:5px solid #edf3f4;"><a href="{% url 'featured_url' %}"><img width="120" height="182" src="{% url 'featured_cover' %}" alt="featured book cover" /></a><br />Today's Free Ebook at Unglue.it
       </div>
       </div>
    </div>

    {% if campaign %}
       <div>Here's a sample widget for the book <span style="font-style: italic">{{campaign.name}}</span> with ISBN {{campaign_isbn}}: <a href="{% url 'widget' campaign_isbn %}">{{base_url}}{% url 'widget' campaign_isbn %}</a>. Copy/paste this into your site:<br /><textarea rows="7" cols="22">&lt;iframe src="{{base_url}}/api/widget/{{campaign_isbn}}/" width="152" height="325" frameborder="0"&gt;&lt;/iframe&gt;</textarea>
       <iframe src="{{base_url}}{% url 'widget' campaign_isbn %}" width="152" height="325" frameborder="0"></iframe>
       
       
       </div>
    {% endif %}
    
    <h3>Basic API info</h3>
    
    <a href="/api/v1/?format=json">Available Resources (JSON)</a>
    
    <p>
    Resources on this list can be accessed via {{ base_url }}/api/v1/{resource_on_list}/?format=json&amp;api_key={your_api_key}&amp;username={your_username} .
    </p>
    
    <p>
    Works can be ordered by how often they've been favorited; append &amp;order_by=num_wishes (ascending) or &amp;order_by=-num_wishes (descending).
    </p>
    <h3>Free Ebooks by ISBN</h3>
    <p>With an API key, you can check if there's a free ebook for any ISBN. ISBNs can be 10 or 13 digits, and can include dashes. This service returns all free-licensed ebooks for a work associated with an ISBN, and for each ebook includes information about file type, rights, and the provider hosting the file.</p>
    <p>For example, here's how to get a list of ebook files for "Homeland".</p>
    <p>{% if user.is_authenticated %}
    JSON: <a href="/api/v1/free/?isbn=9780765333698&amp;format=json&amp;api_key={{api_key}}&amp;username={{user.username}}">{{base_url}}/api/v1/free/?isbn=9780765333698&amp;format=json&amp;api_key={your_api_key}&amp;username={your_username}</a>
    <br />XML: <a href="/api/v1/free/?isbn=9780765333698&amp;format=xml&amp;api_key={{api_key}}&amp;username={{user.username}}">{{base_url}}/api/v1/free/?isbn=9780765333698&amp;format=xml&amp;api_key={your_api_key}&amp;username={your_username}</a>
    {% else %}
    <i>(<a href="{% url 'superlogin' %}?next={% firstof request.get_full_path|urlencode '/' %}">Log in</a> to see links)</i>
    {% endif %}</p>
    <h3>Identifier Resolution</h3>
    <p>Here's how to get work/edition data for an isbn</p>
    <p>{% if user.is_authenticated %}
JSON: <a href="/api/v1/identifier/?format=json&amp;api_key={{api_key}}&amp;username={{user.username}}&amp;type=isbn&amp;value=9780441012039">{{base_url}}/api/v1/identifier/?format=json&amp;api_key={your_api_key}&amp;username={your_username}&amp;type=isbn&amp;value=9780441012039</a><br />
XML: <a href="/api/v1/identifier/?format=xml&amp;api_key={{api_key}}&amp;username={{user.username}}&amp;type=isbn&amp;value=9780441012039">{{base_url}}/api/v1/identifier/?format=xml&amp;api_key={your_api_key}&amp;username={your_username}&amp;type=isbn&amp;value=9780441012039</a></p>    {% else %}
    <i>(<a href="{% url 'superlogin' %}?next={% firstof request.get_full_path|urlencode '/' %}">Log in</a> to see links)</i>
    {% endif %}</p>
    {% if user.is_authenticated %}
    <h3>Campaign info</h3>
    <p>Here's how to get data on all campaigns. if the user is logged in to Unglue.it, they can tell if the campaign book is on their fave list</p>
    <p>JSON: <a href="/api/v1/campaign/?format=json&amp;api_key={{api_key}}&amp;username={{user.username}}">{{base_url}}/api/v1/campaign/?format=json&amp;api_key={your_api_key}&amp;username={your_username}</a><br />XML: <a href="/api/v1/campaign/?format=xml&amp;api_key={{api_key}}&amp;username={{user.username}}">{{base_url}}/api/v1/campaign/?format=json&amp;api_key={your_api_key}&amp;username={your_username}</a></p>
    <h3>Identifier Resolution</h3>
    <p>Here's how to get work/edition data for an isbn</p>
    <p>JSON: <a href="/api/v1/identifier/?format=json&amp;api_key={{api_key}}&amp;username={{user.username}}&amp;type=isbn&amp;value=9780441012039">{{base_url}}/api/v1/identifier/?format=json&amp;api_key={your_api_key}&amp;username={your_username}&amp;type=isbn&amp;value=9780441012039</a><br />
    XML: <a href="/api/v1/identifier/?format=xml&amp;api_key={{api_key}}&amp;username={{user.username}}&amp;type=isbn&amp;value=9780441012039">{{base_url}}/api/v1/identifier/?format=xml&amp;api_key={your_api_key}&amp;username={your_username}&amp;type=isbn&amp;value=9780441012039</a></p>
    <p> In addition to isbn, you can use 'goog' if you have a google books id, and 'oclc' for oclc numbers.</p>
    {% endif %}
    

    <h3>OPDS Catalog Feeds</h3>
    <p>We have a basic implementation of <a href="http://opds-spec.org/specs/opds-catalog-1-1-20110627/">OPDS</a> feeds. You don't need a key to use them. The starting point is <code><a href="{% url 'opds' %}">{{base_url}}{% url 'opds' %}</a></code>. Use the <code>page</code> parameter to page through the results.</p>
    <p>
    Examples:
    <dl>
    <dt>filtered by format</dt>
    <dd><code><a href="{% url 'opds_acqusition' 'epub' %}?page=1">{{base_url}}{% url 'opds_acqusition' 'epub' %}</a></code></dd>
    <dt>filtered by license</dt>
    <dd><code><a href="{% url 'opds_acqusition' 'by-sa' %}?page=1">{{base_url}}{% url 'opds_acqusition' 'by-sa' %}</a></code></dd>
    <dt>filtered by title search</dt>
    <dd><code><a href="{% url 'opds_acqusition' 's.open' %}?page=1">{{base_url}}{% url 'opds_acqusition' 's.open' %}</a></code></dd>
    <dt>filtered by keyword</dt>
    <dd><code><a href="{% url 'opds_acqusition' 'kw.fiction' %}?page=1">{{base_url}}{% url 'opds_acqusition' 'kw.fiction' %}</a></code></dd>
    <dt>filtered by ungluer</dt>
    <dd><code><a href="{% url 'opds_acqusition' '@eric' %}?page=1">{{base_url}}{% url 'opds_acqusition' '@eric' %}</a></code></dd>
    <dt>filtered by having a Project Gutenberg or DOAB identifier (doab, gtbg)</dt>
    <dd><code><a href="{% url 'opds_acqusition' 'doab/-gtbg' %}?page=1">{{base_url}}{% url 'opds_acqusition' 'doab/-gtbg' %}?page=1</a></code></dd>
    </p>
        <p>There's also an OPDS record available for every work on unglue.it. For example, requesting, <code><a href="{% url 'opds_acqusition' 'all'%}?work=13950">{{base_url}}{% url 'opds_acqusition' 'all'%}?work=13950</a></code> get you to the web page or opds record for <i>A Christmas Carol</i>.</p>
   
    <h3>ONIX Catalog Feeds</h3>
    <p>There is an <a href="http://www.editeur.org/12/about-release-3.0/">ONIX 3.0</a> feed corresponding to every facet of our <a href="{% url 'free' %}">free ebook lists</a>. You don't need a key to use them. There is a maximum of 100 books per result you can change with the <code>max</code> parameter. For example, here are the <a href="{% url 'onix' 'by-nc-nd/epub' %}?max=20">first twenty CC BY-ND-ND licensed books available in EPUB.</a> Pages of 30 records each are available via the <code>page</code> parameter. Here's the <a href="{% url 'onix' 'doab' %}?page=1">first page of books from the Directory of Open Access Books.</a></p>
    <p>There's also an ONIX record available for every free ebook on unglue.it.  For example, here is <a href="{% url 'onix_all' %}?work=140086"><i>Issues in Open Research Data</i></a>.</p>
    
    <h3>Identifiers with Content type negotiation</h3>
        <p>There's a URI to identify every work used in OPDS feeds. HTTP content negotiation is used for these ids, so requesting <code>application/atom+xml;profile=opds-catalog;kind=acquisition</code> for  <code><a href="{% url 'work_identifier' '13950'%}">{{base_url}}{% url 'work_identifier' '13950' %}</a></code> get you to the web page or opds record for <i>A Christmas Carol</i>.  requesting <code>text/xml</code> gets you the onix record. Otherwise, you get the normal html page.</p>

{% endblock %}