Merge pull request #9 from exonet/hkr-add-sorting-option

Add option to sort by field

docs/calls.md

@@ -1,5 +1,5 @@
 # Making API calls
-After the client has been initialised, use the `resource` method to define which type of resource you want to get from 
+After the client has been initialised, use the `resource` method to define which type of resource you want to get from
 the API:
 
 ```python
@@ -17,6 +17,9 @@ certificates_request.size(10)
 
 # Set the page to get:
 certificates_request.page(2)
+
+# Order by domain, desc:
+certificates_request.sort('domain', 'desc')
 ```
 
 After setting the options you can call the `get()` method to retrieve the resource:

exonetapi/RequestBuilder.py

@@ -74,6 +74,35 @@ def size(self, page_size):
         self.__query_params['page[size]'] = page_size
         return self
 
+    def sort(self, sort_field, sort_order='asc'):
+        """Prepare this RequestBuilder to sort by a field.
+        :param sort_field: The field name to sort on.
+        :param sort_order: The order for sorting (asc/desc), default: asc.
+        :return: self
+        """
+        if sort_order not in ['asc', 'desc']:
+            raise ValueError('Sort order can only be "asc" or "desc".')
+
+        self.__query_params['sort'] = '{sort}{field}'.format(
+            sort='-' if sort_order == 'desc' else '',
+            field=sort_field,
+        )
+        return self
+
+    def sortAsc(self, sort_field):
+        """Prepare this RequestBuilder to sort by a field in ascending order.
+        :param sort_field: The field name to sort on.
+        :return: self
+        """
+        return self.sort(sort_field, 'asc')
+
+    def sortDesc(self, sort_field):
+        """Prepare this RequestBuilder to sort by a field in descending order.
+        :param sort_field: The field name to sort on.
+        :return: self
+        """
+        return self.sort(sort_field, 'desc')
+
     def related(self, related):
         """Prepare this RequestBuilder to query related resources on the API.
 

tests/testRequestBuilder.py

@@ -50,6 +50,18 @@ def test_size(self):
         self.request_builder.size(30)
         self.assertEqual(self.request_builder._RequestBuilder__query_params['page[size]'], 30)
 
+    def test_sort_default(self):
+        self.request_builder.sort('domain')
+        self.assertEqual(self.request_builder._RequestBuilder__query_params['sort'], 'domain')
+
+    def test_sortAsc(self):
+        self.request_builder.sortAsc('domain')
+        self.assertEqual(self.request_builder._RequestBuilder__query_params['sort'], 'domain')
+
+    def test_sortDesc(self):
+        self.request_builder.sortDesc('domain')
+        self.assertEqual(self.request_builder._RequestBuilder__query_params['sort'], '-domain')
+
     def test_related(self):
         self.request_builder.related('relatedResource')
         self.assertEqual(self.request_builder._RequestBuilder__related, 'relatedResource')