Simple API documentation, filtering tests.

README.md

@@ -64,6 +64,52 @@ My dog is called Cabot and he loves monitoring things. Mainly the presence of fo
 
 It's just a lucky coincidence that his name sounds like he could be an automation tool.
 
+## API
+
+The API has automatically generated documentation available by browsing http(s)://yourcabotserver.example.com/api.  The browsable documentation displays example GET requests and lists other allowed HTTP methods.  
+
+To view individual items, append the item `id` to the url.  For example, to view `graphite_check` 1, browse:
+```
+/api/graphite_checks/1/
+```
+
+### Authentication
+
+The API allows HTTP basic auth using standard Django usernames and passwords as well as session authentication (by submitting the login form on the login page).  The API similarly uses standard Django permissions to allow and deny API access.
+
+All resources are GETable by any authenticated user, but individual permissions must be granted for POST, PUT, and other write methods.
+
+As an example, for POST access to all `status_check` subclasses, add the following permissions:
+```
+cabotapp | status check | Can add graphite status check
+cabotapp | status check | Can add http status check
+cabotapp | status check | Can add icmp status check
+cabotapp | status check | Can add jenkins status check
+```
+
+Access http(s)://yourcabotserver/admin to add/remove users, change user permissions, add/remove groups for group-based permission control, and change group permissions.
+
+### Sorting and Filtering
+
+Sorting and filtering can be used by REST clients to restrict returned resources.  All fields visible in the browsable API can be used for filtering and sorting.
+
+Get all `jenkins_checks` with debounce enabled and CRITICAL importance:
+```
+GET /api/jenkins_checks/?debounce=1&importance=CRITICAL
+```
+
+Sort `graphite_checks` by `name` field, ascending:
+```
+GET /api/graphite_checks/?ordering=name
+```
+
+Sort by `name` field, descending:
+```
+GET /api/graphite_checks/?ordering=-name
+```
+
+Other (non-Cabot specific) examples are available in the [Django REST Framework](http://www.django-rest-framework.org/api-guide/filtering#djangofilterbackend) documentation.
+
 ## License
 
 See `LICENSE` file in this repo.

cabot/cabotapp/tests/tests_basic.py

@@ -612,7 +612,7 @@ class TestAPI(LocalTestCase):
 
     def test_gets(self):
         for model, items in self.start_data.items():
-            response = self.client.get('{}?ordering=id'.format(api_reverse('{}-list'.format(model))),
+            response = self.client.get(api_reverse('{}-list'.format(model)),
                                        format='json', HTTP_AUTHORIZATION=self.basic_auth)
             self.assertEqual(response.status_code, status.HTTP_200_OK)
             self.assertEqual(len(response.data), len(items))
@@ -627,8 +627,11 @@ class TestAPI(LocalTestCase):
     def test_posts(self):
         for model, items in self.post_data.items():
             for item in items:
-                # hackpad_id and other null text fields omitted on create for now due to rest_framework
-                # bug 1879 https://github.com/tomchristie/django-rest-framework/issues/1879
+                # hackpad_id and other null text fields omitted on create 
+                # for now due to rest_framework bug:
+                # https://github.com/tomchristie/django-rest-framework/issues/1879
+                # Update: This has been fixed in master: 
+                # https://github.com/tomchristie/django-rest-framework/pull/1834
                 for field in ('hackpad_id', 'username', 'password'):
                     if field in item:
                         del item[field]
@@ -645,3 +648,99 @@ class TestAPI(LocalTestCase):
                                                format='json', HTTP_AUTHORIZATION=self.basic_auth)
                 self.assertEqual(self.normalize_dict(get_response.data), item)
 
+class TestAPIFiltering(LocalTestCase):
+    def setUp(self):
+        super(TestAPIFiltering, self).setUp()
+
+        self.instance = Instance.objects.create(
+            name='Hello',
+            address='192.168.0.1',
+        )
+        pingcheck = ICMPStatusCheck.objects.create(
+            name='Hello check',
+        )
+        self.instance.status_checks.add(pingcheck)
+
+        self.expected_filter_result = JenkinsStatusCheck.objects.create(
+            name='Filter test 1',
+            debounce=True,
+            importance=Service.CRITICAL_STATUS,
+        )
+        JenkinsStatusCheck.objects.create(
+            name='Filter test 2',
+            debounce=True,
+            importance=Service.WARNING_STATUS,
+        )
+        JenkinsStatusCheck.objects.create(
+            name='Filter test 3',
+            debounce=False,
+            importance=Service.CRITICAL_STATUS,
+        )
+
+        GraphiteStatusCheck.objects.create(
+            name='Z check',
+            metric='stats.fake.value',
+            check_type='>',
+            value='9.0',
+            created_by=self.user,
+            importance=Service.ERROR_STATUS,
+        )
+        GraphiteStatusCheck.objects.create(
+            name='A check',
+            metric='stats.fake.value',
+            check_type='>',
+            value='9.0',
+            created_by=self.user,
+            importance=Service.ERROR_STATUS,
+        )
+        self.expected_sort_names = ['A check', 'Graphite Check', 'Z check']
+
+        self.basic_auth = 'Basic {}'.format(
+            base64.b64encode(
+                '{}:{}'.format(self.username, self.password)
+                    .encode(HTTP_HEADER_ENCODING)
+            ).decode(HTTP_HEADER_ENCODING)
+        )
+
+    def test_query(self):
+        response = self.client.get(
+            '{}?debounce=1&importance=CRITICAL'.format(
+                api_reverse('jenkinsstatuscheck-list')
+            ), 
+            format='json', 
+            HTTP_AUTHORIZATION=self.basic_auth
+        )
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertEqual(len(response.data), 1)
+        self.assertEqual(
+            response.data[0]['id'], 
+            self.expected_filter_result.id
+        )
+    
+    def test_positive_sort(self):
+        response = self.client.get(
+            '{}?ordering=name'.format(
+                api_reverse('graphitestatuscheck-list')
+            ), 
+            format='json', 
+            HTTP_AUTHORIZATION=self.basic_auth
+        )
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertEqual(
+            [item['name'] for item in response.data], 
+            self.expected_sort_names
+        )
+
+    def test_negative_sort(self):
+        response = self.client.get(
+            '{}?ordering=-name'.format(
+                api_reverse('graphitestatuscheck-list')
+            ), 
+            format='json', 
+            HTTP_AUTHORIZATION=self.basic_auth
+        )
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertEqual(
+            [item['name'] for item in response.data], 
+            self.expected_sort_names[::-1]
+        )

cabot/rest_urls.py

@@ -43,7 +43,8 @@ def create_viewset(arg_model, arg_fields, arg_read_only_fields=(), no_create=Fal
     class ViewSet(viewset_class):
         queryset = arg_queryset
         serializer_class = Serializer
-        ordering = ['-id']
+        ordering = ['id']
+        filter_fields = arg_fields
     return ViewSet
 
 check_group_mixin_fields = (