Tweaks to filtering-by-tag, and to its documentation.

hc/api/models.py

@@ -153,6 +153,9 @@ class Check(models.Model):
     def tags_list(self):
         return [t.strip() for t in self.tags.split(" ") if t.strip()]
 
+    def matches_tag_set(self, tag_set):
+        return tag_set.issubset(self.tags_list())
+
     def to_dict(self):
         update_rel_url = reverse("hc-api-update", args=[self.code])
         pause_rel_url = reverse("hc-api-pause", args=[self.code])

hc/api/views.py

@@ -104,24 +104,20 @@ def _update(check, spec):
 @validate_json(schemas.check)
 def checks(request):
     if request.method == "GET":
-        tags = request.GET.getlist('tag', [])
         q = Check.objects.filter(user=request.user)
 
-        doc = {"checks": []}
+        tags = set(request.GET.getlist("tag"))
+        for tag in tags:
+            # approximate filtering by tags
+            q = q.filter(tags__contains=tag)
 
-        if len(tags) > 0:
-            for tag in tags:
-                q = q.filter(tags__contains=tag.strip())
+        checks = []
+        for check in q:
+            # precise, final filtering
+            if not tags or check.matches_tag_set(tags):
+                checks.append(check.to_dict())
 
-            tags_set = set(tags)
-
-            for check in q:
-                if tags_set.issubset(set(check.tags_list())):
-                    doc["checks"].append(check.to_dict())
-        else:
-            doc["checks"] = [check.to_dict() for check in q]
-
-        return JsonResponse(doc)
+        return JsonResponse({"checks": checks})
 
     elif request.method == "POST":
         created = False

templates/front/docs_api.html

@@ -60,22 +60,33 @@ The response may contain a JSON document with additional data.
 
 <div class="api-path">GET {{ SITE_ROOT }}/api/v1/checks/</div>
 
-<p>
-    Returns a list of checks. This API call takes only optional tag querystring parameter to filter checks by their tags.
-    If no parameter provided it returns a JSON document with all checks in user's account.
-</p>
+<p>Returns a list of checks belonging to the user, optionally filtered by
+one or more tags.</p>
+
+<h3 class="api-section">Query String Parameters</h3>
+<table class="table">
+    <tr>
+        <th>tag=&lt;value&gt;</th>
+        <td>
+            <p>
+                Filters the checks, and returns only the checks that
+                are tagged with the specified value.
+            </p>
+            <p>
+                This parameter can be repeated multiple times.
+            </p>
+            <p>Example:</p>
+            <pre>{{ SITE_ROOT }}/api/v1/checks/?tag=foo&amp;tag=bar</pre>
+        </td>
+    </tr>
+</table>
+
 <h3 class="api-section">Example Request</h3>
 {% include "front/snippets/list_checks_request.html" %}
 
 <h3 class="api-section">Example Response</h3>
 {% include "front/snippets/list_checks_response.html" %}
 
-<h3 class="api-section">Example Request To Filter Checks By Their Tags</h3>
-{% include "front/snippets/list_checks_request_filtered.html" %}
-
-<h3 class="api-section">Example Response Of Filtered Checks</h3>
-{% include "front/snippets/list_checks_response_filtered.html" %}
-
 <!-- ********************************************************************** /-->
 
 <a class="section" name="create-check">

templates/front/snippets/list_checks_request_filtered.html

@@ -1,2 +0,0 @@
-<div class="highlight"><pre><span></span>curl --header <span class="s2">&quot;X-Api-Key: your-api-key&quot;</span> {{ SITE_ROOT }}/api/v1/checks/?tag=bar&tag=baz
-</pre></div>

templates/front/snippets/list_checks_request_filtered.txt

@@ -1 +0,0 @@
-curl --header "X-Api-Key: your-api-key" SITE_ROOT/api/v1/checks/?tag=bar&tag=baz

templates/front/snippets/list_checks_response_filtered.html

@@ -1,19 +0,0 @@
-<div class="highlight"><pre><span></span><span class="p">{</span>
-  <span class="nt">&quot;checks&quot;</span><span class="p">:</span> <span class="p">[</span>
-    <span class="p">{</span>
-      <span class="nt">&quot;last_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
-      <span class="nt">&quot;ping_url&quot;</span><span class="p">:</span> <span class="s2">&quot;{{ PING_ENDPOINT }}9d17c61f-5c4f-4cab-b517-11e6b2679ced&quot;</span><span class="p">,</span>
-      <span class="nt">&quot;next_ping&quot;</span><span class="p">:</span> <span class="kc">null</span><span class="p">,</span>
-      <span class="nt">&quot;grace&quot;</span><span class="p">:</span> <span class="mi">3600</span><span class="p">,</span>
-      <span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;Api test 2&quot;</span><span class="p">,</span>
-      <span class="nt">&quot;n_pings&quot;</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span>
-      <span class="nt">&quot;tags&quot;</span><span class="p">:</span> <span class="s2">&quot;bar baz&quot;</span><span class="p">,</span>
-      <span class="nt">&quot;pause_url&quot;</span><span class="p">:</span> <span class="s2">&quot;{{ SITE_ROOT }}/api/v1/checks/9d17c61f-5c4f-4cab-b517-11e6b2679ced/pause&quot;</span><span class="p">,</span>
-      <span class="nt">&quot;tz&quot;</span><span class="p">:</span> <span class="s2">&quot;UTC&quot;</span><span class="p">,</span>
-      <span class="nt">&quot;schedule&quot;</span><span class="p">:</span> <span class="s2">&quot;0/10 * * * *&quot;</span><span class="p">,</span>
-      <span class="nt">&quot;status&quot;</span><span class="p">:</span> <span class="s2">&quot;new&quot;</span><span class="p">,</span>
-      <span class="nt">&quot;update_url&quot;</span><span class="p">:</span> <span class="s2">&quot;{{ SITE_ROOT }}/api/v1/checks/9d17c61f-5c4f-4cab-b517-11e6b2679ced&quot;</span>
-    <span class="p">}</span>
-  <span class="p">]</span>
-<span class="p">}</span>
-</pre></div>

templates/front/snippets/list_checks_response_filtered.txt

@@ -1,18 +0,0 @@
-{
-  "checks": [
-    {
-      "last_ping": null,
-      "ping_url": "PING_ENDPOINT9d17c61f-5c4f-4cab-b517-11e6b2679ced",
-      "next_ping": null,
-      "grace": 3600,
-      "name": "Api test 2",
-      "n_pings": 0,
-      "tags": "bar baz",
-      "pause_url": "SITE_ROOT/api/v1/checks/9d17c61f-5c4f-4cab-b517-11e6b2679ced/pause",
-      "tz": "UTC",
-      "schedule": "0/10 * * * *",
-      "status": "new",
-      "update_url": "SITE_ROOT/api/v1/checks/9d17c61f-5c4f-4cab-b517-11e6b2679ced"
-    }
-  ]
-}