api info page, some api fixes
authorRadek Czajka <radoslaw.czajka@nowoczesnapolska.org.pl>
Mon, 12 Sep 2011 03:30:51 +0000 (05:30 +0200)
committerRadek Czajka <radoslaw.czajka@nowoczesnapolska.org.pl>
Mon, 12 Sep 2011 03:36:36 +0000 (05:36 +0200)
apps/api/handlers.py
apps/api/locale/pl/LC_MESSAGES/django.mo [new file with mode: 0644]
apps/api/locale/pl/LC_MESSAGES/django.po [new file with mode: 0644]
apps/api/templates/api/main.html [new file with mode: 0755]
apps/api/tests.py
apps/api/urls.py

index 32a3ce3..73ca07c 100644 (file)
@@ -135,11 +135,17 @@ class BooksHandler(BaseHandler):
         tags = read_tags(tags, allowed=self.categories)
         if tags:
             if top_level:
-                return Book.tagged_top_level(tags)
+                books = Book.tagged_top_level(tags)
+                return books if books else rc.NOT_FOUND
             else:
-                return Book.tagged.with_all(tags)
+                books = Book.tagged.with_all(tags)
         else:
-            return Book.objects.all()
+            books = Book.objects.all()
+
+        if books.exists():
+            return books
+        else:
+            return rc.NOT_FOUND
 
 
 # add categorized tags fields for Book
@@ -201,7 +207,13 @@ class TagsHandler(BaseHandler):
         except KeyError, e:
             return rc.NOT_FOUND
 
-        return Tag.objects.filter(category=category_sng)
+        tags = Tag.objects.filter(category=category_sng)
+        tags = [t for t in tags if t.get_count() > 0]
+        if tags:
+            return tags
+        else:
+            return rc.NOT_FOUND
+
 
     @classmethod
     def href(cls, tag):
@@ -240,7 +252,11 @@ class FragmentsHandler(BaseHandler):
 
         """
         tags = read_tags(tags, allowed=self.categories)
-        return Fragment.tagged.with_all(tags).select_related('book')
+        fragmets = Fragment.tagged.with_all(tags).select_related('book')
+        if fragments.exists():
+            return fragments
+        else:
+            return rc.NOT_FOUND
 
     @classmethod
     def href(cls, fragment):
diff --git a/apps/api/locale/pl/LC_MESSAGES/django.mo b/apps/api/locale/pl/LC_MESSAGES/django.mo
new file mode 100644 (file)
index 0000000..4d71392
Binary files /dev/null and b/apps/api/locale/pl/LC_MESSAGES/django.mo differ
diff --git a/apps/api/locale/pl/LC_MESSAGES/django.po b/apps/api/locale/pl/LC_MESSAGES/django.po
new file mode 100644 (file)
index 0000000..bd1c182
--- /dev/null
@@ -0,0 +1,125 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
+# This file is distributed under the same license as the PACKAGE package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: PACKAGE VERSION\n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2011-09-12 05:20+0200\n"
+"PO-Revision-Date: 2011-09-12 05:22+0100\n"
+"Last-Translator: Radek Czajka <radoslaw.czajka@nowoczesnapolska.org.pl>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"Language: \n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=3; plural=(n==1 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2);\n"
+
+#: templates/api/main.html:4
+msgid "WolneLektury.pl API"
+msgstr "API serwisu WolneLektury.pl"
+
+#: templates/api/main.html:13
+msgid ""
+"\n"
+"WolneLektury.pl API resides under <code>http://www.wolnelektury.pl/api/</code>.\n"
+"You can use it to access information about books, their fragments and\n"
+"their metadata.\n"
+msgstr ""
+"\n"
+"API serwisu WolneLektury.pl znajduje się pod adresem <code>http://www.wolnelektury.pl/api/</code>.\n"
+"Za jego pomocą można uzyskać informacje o utworach, ich fragmentach i metadanych.\n"
+
+#: templates/api/main.html:21
+msgid ""
+"\n"
+"Default data serialization format is\n"
+"<a href=\"http://en.wikipedia.org/wiki/JSON\">JSON</a>,\n"
+"but you can also use XML by appending <code>?format=xml</code>\n"
+"query parameter to each URL.\n"
+msgstr ""
+"\n"
+"Dane domyślnie są serializowane w formacie <a href=\"http://pl.wikipedia.org/wiki/JSON\">JSON</a>,ale dostępny jest też format XML – wystarczy dodać parametr <code>?format=xml</code>\n"
+"do każdego zapytania.\n"
+
+#: templates/api/main.html:30
+msgid ""
+"\n"
+"The URLs in WolneLektury.pl API are:\n"
+msgstr ""
+"\n"
+"API Wolnych Lektur zawiera następujące adresy URL:\n"
+
+#: templates/api/main.html:36
+msgid "List of all books"
+msgstr "Lista utworów"
+
+#: templates/api/main.html:38
+msgid "List of all authors"
+msgstr "Lista autorów"
+
+#: templates/api/main.html:39
+msgid "List of all epochs"
+msgstr "Lista epok"
+
+#: templates/api/main.html:40
+msgid "List of all genres"
+msgstr "Lista gatunków literackich"
+
+#: templates/api/main.html:41
+msgid "List of all kinds"
+msgstr "Lista rodzajów literackich"
+
+#: templates/api/main.html:43
+msgid "List of all themes"
+msgstr "Lista motywów i tematów literackich"
+
+#: templates/api/main.html:49
+#, python-format
+msgid ""
+"\n"
+"Each element of those lists contains a link (in a \"href\") attibute\n"
+"which points to individual resource's details, i.e.:\n"
+"<a href=\"%(e1)s\">%(e1)s</a> or\n"
+"<a href=\"%(e2)s\">%(e2)s</a>.\n"
+msgstr ""
+"\n"
+"Każdy element na tych listach zawiera adres (w atrybucie „href”), pod którym można znaleźć szczegółowe dane, np. <a href=\"%(e1)s\">%(e1)s</a> czy <a href=\"%(e2)s\">%(e2)s</a>.\n"
+
+#: templates/api/main.html:58
+#, python-format
+msgid ""
+"\n"
+"You can combine authors, epochs, genres and kinds to find only books matching\n"
+"those criteria. For instance:\n"
+"<a href=\"%(e)s\">%(e)s</a>.\n"
+msgstr ""
+"\n"
+"Można łączyć autorów, epoki, gatunki i rodzaje, aby wybrać tylko utwory odpowiadające zadanym kryteriom. Na przykład: <a href=\"%(e)s\">%(e)s</a>.\n"
+
+#: templates/api/main.html:66
+#, python-format
+msgid ""
+"\n"
+"If you only want top-level books and not all the children, you can use /parent_books/, as in:\n"
+"<a href=\"%(e)s\">%(e)s</a>.\n"
+msgstr ""
+"\n"
+"Aby spośród wszystkich pasujących wybrać tylko utwory najwyższego poziomu (pomijając ich podutwory), można użyć zapytania /parent_books/, np.: <a href=\"%(e)s\">%(e)s</a>.\n"
+
+#: templates/api/main.html:74
+#, python-format
+msgid ""
+"\n"
+"The same way, using also books and themes, you can search for a list of fragments:\n"
+"<a href=\"%(e)s\">%(e)s</a>. \n"
+"Again, each entry has a \"href\" attribute which links to the fragment's details, i.e.:\n"
+"<a href=\"%(f)s\">%(f)s</a>. \n"
+msgstr ""
+"\n"
+"W ten sam sposób, filtrując dodatkowo według lektur lub motywów, można wyszukiwać fragmenty:<a href=\"%(e)s\">%(e)s</a>. \n"
+"Każdy element uzyskanej listy w atrybucie „href” zawiera link do szczegółowego opisu danego fragmentu, np.:\n"
+"<a href=\"%(f)s\">%(f)s</a>. \n"
+
diff --git a/apps/api/templates/api/main.html b/apps/api/templates/api/main.html
new file mode 100755 (executable)
index 0000000..ada5093
--- /dev/null
@@ -0,0 +1,82 @@
+{% extends "base.html" %}
+{% load i18n %}
+
+{% block title %}{% trans "WolneLektury.pl API" %}{% endblock %}
+
+{% block bodyid %}api{% endblock %}
+
+{% block body %}
+
+<h1>API</h1>
+
+<p>
+{% blocktrans %}
+WolneLektury.pl API resides under <code>http://www.wolnelektury.pl/api/</code>.
+You can use it to access information about books, their fragments and
+their metadata.
+{% endblocktrans %}
+</p>
+
+<p>
+{% blocktrans %}
+Default data serialization format is
+<a href="http://en.wikipedia.org/wiki/JSON">JSON</a>,
+but you can also use XML by appending <code>?format=xml</code>
+query parameter to each URL.
+{% endblocktrans %}
+</p>
+
+<p>
+{% blocktrans %}
+The URLs in WolneLektury.pl API are:
+{% endblocktrans %}
+</p>
+
+<ul>
+    <li><a href='/api/books/'>/api/books/</a> – {% trans "List of all books" %}
+
+    <li><a href='/api/authors/'>/api/authors/</a> – {% trans "List of all authors" %}</li>
+    <li><a href='/api/epochs/'>/api/epochs/</a> – {% trans "List of all epochs" %}</li>
+    <li><a href='/api/genres/'>/api/genres/</a> – {% trans "List of all genres" %}</li>
+    <li><a href='/api/kinds/'>/api/kinds/</a> – {% trans "List of all kinds" %}</li>
+
+    <li><a href='/api/themes/'>/api/themes/</a> – {% trans "List of all themes" %}</li>
+</ul>
+
+<p>
+{% url api_book "studnia-i-wahadlo" as e1 %}
+{% url api_tag "authors" "edgar-allan-poe" as e2 %}
+{% blocktrans %}
+Each element of those lists contains a link (in a "href") attibute
+which points to individual resource's details, i.e.:
+<a href="{{e1}}">{{e1}}</a> or
+<a href="{{e2}}">{{e2}}</a>.
+{% endblocktrans %}
+</p>
+
+<p>
+{% blocktrans with "/api/authors/adam-mickiewicz/kinds/liryka/books/" as e %}
+You can combine authors, epochs, genres and kinds to find only books matching
+those criteria. For instance:
+<a href="{{e}}">{{e}}</a>.
+{% endblocktrans %}
+</p>
+
+<p>
+{% blocktrans with "/api/authors/adam-mickiewicz/kinds/liryka/parent_books/" as e %}
+If you only want top-level books and not all the children, you can use /parent_books/, as in:
+<a href="{{e}}">{{e}}</a>.
+{% endblocktrans %}
+</p>
+
+<p>
+{% url api_fragment "sen-nocy-letniej" "1290526312912-3814598192" as f %}
+{% blocktrans with "/api/authors/william-shakespeare/themes/zabawa/fragments/" as e %}
+The same way, using also books and themes, you can search for a list of fragments:
+<a href="{{e}}">{{e}}</a>. 
+Again, each entry has a "href" attribute which links to the fragment's details, i.e.:
+<a href="{{f}}">{{f}}</a>. 
+{% endblocktrans %}
+</p>
+
+{% endblock %}
index 12c7126..2c2e51c 100644 (file)
@@ -122,6 +122,9 @@ class TagTests(TestCase):
 
     def setUp(self):
         self.tag = Tag.objects.create(category='author', slug='joe', name='Joe')
+        self.book = Book.objects.create(title='A Book', slug='a-book')
+        self.book.tags = [self.tag]
+        self.book.save()
 
     def test_tag_list(self):
         tags = json.loads(self.client.get('/api/authors/').content)
index ec2c2e7..89bb600 100644 (file)
@@ -20,6 +20,10 @@ fragment_list_resource = Resource(handler=handlers.FragmentsHandler)
 
 
 urlpatterns = patterns('',
+    url(r'^$', 'django.views.generic.simple.direct_to_template',
+            {'template': 'api/main.html'}),
+
+
     # changes handlers
     url(r'^book_changes/(?P<since>\d*?)\.(?P<emitter_format>xml|json|yaml)$', book_changes_resource),
     url(r'^tag_changes/(?P<since>\d*?)\.(?P<emitter_format>xml|json|yaml)$', tag_changes_resource),