Merge pull request #4 from d3rky/feature/docs-getting-started

Add simple quickstart guide in documentation

Author: d3rky

README.md

@@ -8,7 +8,7 @@ Django RQL
 RQL
 ---
 
-RQL (Resource query language) is designed for modern application development. It is built for the web, ready for NoSQL, and highly extensible with simple syntax. 
+RQL (Resource query language) is designed for modern application development. It is built for the web, ready for NoSQL, and highly extensible with simple syntax.
 This is a query language fast and convenient database interaction. RQL was designed for use in URLs to request object-style data structures.
 
 
@@ -27,11 +27,16 @@ Currently supported operators
 1. Comparison (eq, ne, gt, ge, lt, le, like, ilike, search)
 0. List (in, out)
 0. Logical (and, or, not)
-0. Constants (null(), empty()) 
+0. Constants (null(), empty())
 0. Ordering (ordering)
 0. Select (select)
 
 
+Quickstart
+==========
+Try to enrich your API filtering opportunities learning [Quickstart Guide][quickstart]
+
+
 Example
 =======
 ```python
@@ -47,17 +52,17 @@ class ModelFilterClass(RQLFilterClass):
     DISTINCT - Boolean flag, that specifies if queryset must always be DISTINCT
     SELECT - Boolean flag, that specifies if Filter Class supports select operations and queryset optimizations
     OPENAPI_SPECIFICATION - Python class that renders OpenAPI specification
-    
+
     Filters can be set in two ways:
         1) string (default settings are calculated from ORM)
         2) dict (overriding settings for specific cases)
-        
+
     Filter Dict Structure
     {
         'filter': str
         # or
         'namespace': str
-        
+
         'source': str
         # or
         'sources': iterable
@@ -66,17 +71,17 @@ class ModelFilterClass(RQLFilterClass):
         # or
         'dynamic': bool
         'field': obj
-        
+
         'lookups': set
-        
+
         'qs': obj
-        
+
         'use_repr': bool  # can't be used in namespaces
         'ordering': bool  # can't be true if 'use_repr=True'
         'search': bool    # can't be true if 'use_repr=True'
         'hidden': bool
     }
-    
+
     """
     MODEL = Model
     FILTERS = ['id', {
@@ -105,7 +110,7 @@ class ModelFilterClass(RQLFilterClass):
         'filters': ['id', 'name'],  # will be converted to `author.id` and `author.name`
     },{
         # `distinct` needs to be setup for filters that require QS to work in DISTINCT mode
-        # `openapi` configuration is automatically collected by OpenAPI autogenerator 
+        # `openapi` configuration is automatically collected by OpenAPI autogenerator
         'filter': 'published.at',
         'source': 'published_at',
         'distinct': True,
@@ -148,7 +153,7 @@ class ModelFilterClass(RQLFilterClass):
         'lookups': {FilterLookups.EQ, FilterLookups.IN, FilterLookups.I_LIKE},
         'ordering': True,
         'search': True,
-        
+
         'custom_data': [1],
     }]
 
@@ -177,7 +182,7 @@ Django Rest Framework Extensions
 1. Pagination (limit, offset)
 0. Support for custom fields, inherited at any depth from basic model fields, like CharField().
 0. Backend `DjangoFiltersRQLFilterBackend` with automatic conversion of [Django-Filters](https://django-filter.readthedocs.io/en/master/) query to RQL query.
-0. OpenAPI docs are autogenerated for filer classes.
+0. OpenAPI docs are autogenerated for filter classes.
 
 Best Practices
 ==============
@@ -201,9 +206,11 @@ Testing
 Check code style: `flake8`
 Run tests: `pytest`
 
-Tests reports are generated in `tests/reports`. 
+Tests reports are generated in `tests/reports`.
 * `out.xml` - JUnit test results
 * `coverage.xml` - Coverage xml results
 
 To generate HTML coverage reports use:
 `--cov-report html:tests/reports/cov_html`
+
+[quickstart]: ./docs/quickstart.md

docs/quickstart.md

@@ -0,0 +1,86 @@
+Quickstart
+==========
+
+We're going to create a simple API and configure filters to support RQL syntax.
+
+
+Installation
+------------
+Install `django-rql` library in your existing or new Django and Django REST Framework project using command
+
+```
+pip install django-rql
+```
+
+Configuring Django settings
+---------------------------
+
+Setup default `filter_backends` in your Django settings file
+
+```
+REST_FRAMEWORK = {
+    'DEFAULT_FILTER_BACKENDS': ['dj_rql.drf.RQLFilterBackend']
+}
+```
+
+Now your APIs are supporting RQL syntax for query strings. Let's write some filters
+
+Write your first RQL Filter Class
+---------------------------------
+
+For writing your first RQL Filter Class you need some models to be ready. Let's imagine you have simple Domain Model in your project, that can be represented as several models like below
+
+```
+from django.db import models
+
+
+class Product(models.Model):
+    name = models.CharField()
+```
+
+Let's create an RQL Filter Class for `Product` model. All you need is to inherit from `dj_rql.filter_cls.RQLFilterClass`, define `MODEL` property and add supported `FILTERS` for class
+
+```
+from dj_rql.filter_cls import RQLFilterClass
+
+
+class ProductFilters(RQLFilterClass):
+    MODEL = Product
+    FILTERS = (
+        'id',
+        'name',
+    )
+
+```
+
+Using simple strings in `FILTERS` property you can define what fields are available for filtering. In example above you allow filtering only by `id` and `name` filter
+
+Add RQL Filter Class to DRF View
+--------------------------------
+
+In your latest step you need to add `ProductFilters` class as a `rql_filter_class` property inside your View
+
+```
+class ProductsViewSet(mixins.ListModelMixin, GenericViewSet):
+    queryset = Product.objects.all()
+    serializer_class = ProductSerializer
+    rql_filter_class = ProductFilters
+```
+
+And that's it! Now you are able to start your local server and try to filter using RQL syntax
+
+```
+curl http://127.0.0.1:8080/api/v1/products?like(name,Unicorn*)|eq(name,LLC)
+```
+
+For learning RQL Syntax use following links:
+
+[RQL Reference][rql_reference]
+
+[RQL for Web][rql_for_web]
+
+For learning how to define more complex filters use [Filters Guide][filters_guide]
+
+[rql_reference]: https://connect.cloudblue.com/community/api/rql/
+[rql_for_web]: https://www.sitepen.com/blog/resource-query-language-a-query-language-for-the-web-nosql/
+[filters_guide]: ./filters_guide.md