Skip to content

Commit ffb772f

Browse files
author
Pavel Lonkin
committed
Add Quickstart Guide in docs
1 parent 2e9518a commit ffb772f

File tree

2 files changed

+93
-0
lines changed

2 files changed

+93
-0
lines changed

README.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,11 @@ Currently supported operators
3232
0. Select (select)
3333

3434

35+
Quickstart
36+
==========
37+
Try to enrich your API filtering opportunities learning [Quickstart Guide][quickstart]
38+
39+
3540
Example
3641
=======
3742
```python
@@ -207,3 +212,5 @@ Tests reports are generated in `tests/reports`.
207212

208213
To generate HTML coverage reports use:
209214
`--cov-report html:tests/reports/cov_html`
215+
216+
[quickstart]: ./docs/quickstart.md

docs/quickstart.md

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
Quickstart
2+
==========
3+
4+
We're going to create a simple API and configure filters to support RQL syntax.
5+
6+
7+
Installation
8+
------------
9+
Install `django-rql` library in your existing or new Django and Django REST Framework project using command
10+
11+
```
12+
pip install django-rql
13+
```
14+
15+
Configuring Django settings
16+
---------------------------
17+
18+
Setup default `filter_backends` in your Django settings file
19+
20+
```
21+
REST_FRAMEWORK = {
22+
'DEFAULT_FILTER_BACKENDS': ['dj_rql.drf.RQLFilterBackend']
23+
}
24+
```
25+
26+
Now your APIs are supporting RQL syntax for query strings. Let's write some filters
27+
28+
Write your first RQL Filter Class
29+
---------------------------------
30+
31+
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
32+
33+
```
34+
from django.db import models
35+
36+
37+
class Product(models.Model):
38+
name = models.CharField()
39+
```
40+
41+
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
42+
43+
```
44+
from dj_rql.filter_cls import RQLFilterClass
45+
46+
47+
class ProductFilters(RQLFilterClass):
48+
MODEL = Product
49+
FILTERS = (
50+
'id',
51+
'name',
52+
)
53+
54+
```
55+
56+
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
57+
58+
Add RQL Filter Class to DRF View
59+
--------------------------------
60+
61+
In your latest step you need to add `ProductFilters` class as a `rql_filter_class` property inside your View
62+
63+
```
64+
class ProductsViewSet(mixins.ListModelMixin, GenericViewSet):
65+
queryset = Product.objects.all()
66+
serializer_class = ProductSerializer
67+
rql_filter_class = ProductFilters
68+
```
69+
70+
And that's it! Now you are able to start your local server and try to filter using RQL syntax
71+
72+
```
73+
curl http://127.0.0.1:8080/api/v1/products?like(name,Unicorn*)|eq(name,LLC)
74+
```
75+
76+
For learning RQL Syntax use following links:
77+
78+
[RQL Reference][rql_reference]
79+
80+
[RQL for Web][rql_for_web]
81+
82+
For learning how to define more complex filters use [Filters Guide][filters_guide]
83+
84+
[rql_reference]: https://connect.cloudblue.com/community/api/rql/
85+
[rql_for_web]: https://www.sitepen.com/blog/resource-query-language-a-query-language-for-the-web-nosql/
86+
[filters_guide]: ./filters_guide.md

0 commit comments

Comments
 (0)