Issue #290: Allow disabling URL parameters.

README.md

@@ -202,6 +202,16 @@ array(
 );
 ```
 
+The sort parameter can be disabled in your resource plugin definition:
+
+```php
+$plugin = array(
+  ...
+  'url_params' => array(
+    'sort' => FALSE,
+  ),
+);
+
 You can also define default sort fields in your plugin, by overriding
 `defaultSortInfo()` in your class definition.
 
@@ -220,7 +230,6 @@ class MyPlugin extends \RestfulEntityBaseTaxonomyTerm {
     return array('id' => 'DESC');
   }
 }
-
 ```
 
 ### Filter
@@ -233,6 +242,17 @@ $request['filter'] = array('label' => 'abc');
 $result = $handler->get('', $request);
 ```
 
+The filter parameter can be disabled in your resource plugin definition:
+
+```php
+$plugin = array(
+  ...
+  'url_params' => array(
+    'filter' => FALSE,
+  ),
+);
+```
+
 ### Autocomplete
 By passing the autocomplete query string in the request, it is possible to change
 the normal listing behavior into autocomplete.
@@ -254,6 +274,27 @@ $request = array(
 $handler->get('', $request);
 ```
 
+### Range
+RESTful allows you to cotrol the number of elements per page you want to show. This value will always be limited by the `$range` variable in your resource class. This variable, in turn, defaults to 50.
+
+```php
+$handler = restful_get_restful_handler('articles');
+// Single value property.
+$request['range'] = 25;
+$result = $handler->get('', $request);
+```
+
+The range parameter can be disabled in your resource plugin definition:
+
+```php
+$plugin = array(
+  ...
+  'url_params' => array(
+    'range' => FALSE,
+  ),
+);
+```
+
 ## API via URL
 
 ### View an Article
@@ -308,6 +349,14 @@ RESTful allows filtering of a list.
 curl https://example.com/api/v1/articles?filter[label]=abc
 ```
 
+You can even filter results using basic operators. For instance to get all the
+articles after a certain date:
+
+```shell
+# Handler v1.0
+curl https://example.com/api/articles?filter[created][value]=1417591992&filter[created][operator]=">="
+```
+
 ## Authentication providers
 
 Restful comes with ``cookie``, ``base_auth`` (user name and password in the HTTP header)

includes/RestfulManager.php

@@ -100,6 +100,9 @@ class RestfulManager {
    *   it does not match the allow_origin value the access will be denied.
    *   Typically used to avoid CORS problems. This will also populate the
    *   Access-Control-Allow-Origin header in the response.
+   * - url_params: Associative array to configure if the "sort", "filter" and
+   *   "range" url parameters should be allowed. Defaults to TRUE in all of
+   *   them.
    */
   public static function pluginProcessRestful($plugin, $info) {
     $plugin += array(
@@ -117,6 +120,7 @@ public static function pluginProcessRestful($plugin, $info) {
       'discoverable' => TRUE,
       'data_provider_options' => array(),
       'menu_item' => FALSE,
+      'url_params' => array(),
     );
 
     $plugin['render_cache'] += array(
@@ -133,6 +137,12 @@ public static function pluginProcessRestful($plugin, $info) {
       'range' => 10,
     );
 
+    $plugin['url_params'] += array(
+      'sort' => TRUE,
+      'range' => TRUE,
+      'filter' => TRUE,
+    );
+
     if (!empty($plugin['rate_limit'])) {
       foreach ($plugin['rate_limit'] as $event_name => $rate_limit_info) {
         $plugin['rate_limit'][$event_name]['limits'] += array('anonymous user' => 0);

plugins/restful/RestfulBase.php

@@ -665,6 +665,11 @@ public function process($path = '', array $request = array(), $method = \Restful
     $this->setRequest($request);
     // Override the range with the value in the URL.
     if (!empty($request['range'])) {
+      $url_params = $this->getPluginKey('url_params');
+      if (!$url_params['range']) {
+        throw new \RestfulBadRequestException('The range parameter has been disabled in server configuration.');
+      }
+
       if (!ctype_digit((string) $request['range']) || $request['range'] < 1) {
         throw new \RestfulBadRequestException('"Range" property should be numeric and higher than 0.');
       }
@@ -779,10 +784,15 @@ protected function parseRequestForListSort() {
     $request = $this->getRequest();
     $public_fields = $this->getPublicFields();
 
-    $sorts = array();
     if (empty($request['sort'])) {
       return array();
     }
+    $url_params = $this->getPluginKey('url_params');
+    if (!$url_params['sort']) {
+      throw new \RestfulBadRequestException('Sort parameters have been disabled in server configuration.');
+    }
+
+    $sorts = array();
     foreach (explode(',', $request['sort']) as $sort) {
       $direction = $sort[0] == '-' ? 'DESC' : 'ASC';
       $sort = str_replace('-', '', $sort);
@@ -840,6 +850,10 @@ protected function parseRequestForListFilter() {
       // No filtering is needed.
       return array();
     }
+    $url_params = $this->getPluginKey('url_params');
+    if (!$url_params['filter']) {
+      throw new \RestfulBadRequestException('Filter parameters have been disabled in server configuration.');
+    }
 
     $filters = array();
     $public_fields = $this->getPublicFields();

tests/RestfulListTestCase.test

@@ -195,6 +195,21 @@ class RestfulListTestCase extends RestfulCurlBaseTestCase {
       $this->pass('Exception thrown on illegal sort property, descending.');
     }
 
+    // Test valid sort with sort params disabled.
+    $handler->setPluginKey('url_params', array(
+      'filter' => TRUE,
+      'sort' => FALSE,
+      'range' => TRUE,
+    ));
+    $request['sort'] = 'label,id';
+    try {
+      $handler->get('', $request);
+      $this->fail('Exception not raised for disabled sort parameter.');
+    }
+    catch (\RestfulBadRequestException $e) {
+      $this->pass('Exception raised for disabled sort parameter.');
+    }
+
     // Test the range overrides.
     unset($request['sort']);
     $request['range'] = 2;
@@ -211,6 +226,21 @@ class RestfulListTestCase extends RestfulCurlBaseTestCase {
       $this->pass('Exception raised on invalid range parameter.');
     }
 
+    // Test valid range with range params disabled.
+    $handler->setPluginKey('url_params', array(
+      'filter' => TRUE,
+      'sort' => TRUE,
+      'range' => FALSE,
+    ));
+    $request['range'] = 2;
+    try {
+      $handler->get('', $request);
+      $this->fail('Exception not raised for disabled range parameter.');
+    }
+    catch (\RestfulBadRequestException $e) {
+      $this->pass('Exception raised for disabled range parameter.');
+    }
+
     // Test the administrator's content listing.
     $role_name = 'administrator';
     $handler = restful_get_restful_handler_by_name('per_role_content__1_0:' . $role_name);
@@ -328,6 +358,21 @@ class RestfulListTestCase extends RestfulCurlBaseTestCase {
     $query = array('filter' => array('invalid-key' => 'foo'));
     $result = $this->httpRequest('api/v1.0/articles/1', \RestfulInterface::GET, $query);
     $this->assertEqual($result['code'], '200', 'Invalid filter key was ignored on non-list query.');
+
+    // Test valid filter with filter params disabled.
+    $handler->setPluginKey('url_params', array(
+      'filter' => FALSE,
+      'sort' => TRUE,
+      'range' => TRUE,
+    ));
+    $request['filter'] = array('label' => 'abc');
+    try {
+      $handler->get('', $request);
+      $this->fail('Exception not raised for disabled filter parameter.');
+    }
+    catch (\RestfulBadRequestException $e) {
+      $this->pass('Exception raised for disabled filter parameter.');
+    }
   }
 
   /**