105 lines
9.1 KiB
HTML
105 lines
9.1 KiB
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"><iframe src="{{base_url}}/api/widget/featured/" width="152" height="325" frameborder="0"></iframe></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"><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="{{base_url}}{% url 'featured_url' %}">
|
|
<img width="120" height="182" src="{{base_url}}{% url 'featured_cover' %}" alt="unglue.it featured book" />
|
|
</a></div></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"><iframe src="{{base_url}}/api/widget/{{campaign_isbn}}/" width="152" height="325" frameborder="0"></iframe></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&api_key={your_api_key}&username={your_username} .
|
|
</p>
|
|
|
|
<p>
|
|
Works can be ordered by how often they've been favorited; append &order_by=num_wishes (ascending) or &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&format=json&api_key={{api_key}}&username={{user.username}}">{{base_url}}/api/v1/free/?isbn=9780765333698&format=json&api_key={your_api_key}&username={your_username}</a>
|
|
<br />XML: <a href="/api/v1/free/?isbn=9780765333698&format=xml&api_key={{api_key}}&username={{user.username}}">{{base_url}}/api/v1/free/?isbn=9780765333698&format=xml&api_key={your_api_key}&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&api_key={{api_key}}&username={{user.username}}&type=isbn&value=9780441012039">{{base_url}}/api/v1/identifier/?format=json&api_key={your_api_key}&username={your_username}&type=isbn&value=9780441012039</a><br />
|
|
XML: <a href="/api/v1/identifier/?format=xml&api_key={{api_key}}&username={{user.username}}&type=isbn&value=9780441012039">{{base_url}}/api/v1/identifier/?format=xml&api_key={your_api_key}&username={your_username}&type=isbn&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&api_key={{api_key}}&username={{user.username}}">{{base_url}}/api/v1/campaign/?format=json&api_key={your_api_key}&username={your_username}</a><<br />XML: <a href="/api/v1/campaign/?format=xml&api_key={{api_key}}&username={{user.username}}">{{base_url}}/api/v1/campaign/?format=json&api_key={your_api_key}&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&api_key={{api_key}}&username={{user.username}}&type=isbn&value=9780441012039">{{base_url}}/api/v1/identifier/?format=json&api_key={your_api_key}&username={your_username}&type=isbn&value=9780441012039</a><br />
|
|
XML: <a href="/api/v1/identifier/?format=xml&api_key={{api_key}}&username={{user.username}}&type=isbn&value=9780441012039">{{base_url}}/api/v1/identifier/?format=xml&api_key={your_api_key}&username={your_username}&type=isbn&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></p>
|
|
<p>
|
|
Examples:
|
|
<dl>
|
|
<dt>filtered by format</dt>
|
|
<dd><code><a href="{% url 'opds_acqusition' 'epub' %}">{{base_url}}{% url 'opds_acqusition' 'epub' %}</a></code></dd>
|
|
<dt>filtered by license</dt>
|
|
<dd><code><a href="{% url 'opds_acqusition' 'by-sa' %}">{{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' %}">{{base_url}}{% url 'opds_acqusition' 's.open' %}</a></code></dd>
|
|
<dt>filtered by keyword</dt>
|
|
<dd><code><a href="{% url 'opds_acqusition' 'kw.fiction' %}">{{base_url}}{% url 'opds_acqusition' 'kw.fiction' %}</a></code></dd>
|
|
<dt>filtered by ungluer</dt>
|
|
<dd><code><a href="{% url 'opds_acqusition' '@eric' %}">{{base_url}}{% url 'opds_acqusition' '@eric' %}</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 max parameter. For example, here are the <a href="{% url 'onix' 'by-nc-nd/epub' %}">first hundred CC BY-ND-ND licensed books available in EPUB.</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 %}
|
|
|
|
|