Update docs with additional examples

Author: akopdev

README.md

@@ -4,66 +4,75 @@ Easy way to communicate with bitrix24 portal over REST without OAuth 2.0
 
 ## Description
 
-Bitrix24 REST is a simple API wrapper for working with Bitrix24
-REST API over webhooks.
+Bitrix24 REST is an API wrapper for working with Bitrix24 REST API over webhooks.
+No OAuth 2.0 required. It's easy to use and super lightweight, with minimal dependencies.
 
 ## Features
 
-- Works both with cloud and on-premises versions of bitrix24, much more
-- Super easy for setting up. No OAuth implemetation required
-- Compatible with latests Bitrix24 REST API
-
-## Requirements
-- Python 2.6+ or 3.2+
-- requests
+- Works with both cloud and on-premises versions of Bitrix24.
+- Super easy to setup. No OAuth 2.0 infrastructure required.
+- Built with data analysis in mind and fully compatible with Jupyter Notebook.
+- Fetch paginated data at once without hassle.
+- Works with large datasets and handles rate limits.
 
 ## Installation
+
 ```
 pip install bitrix24-rest
 ```
 
 ## Quickstart
 
 ```python
-from bitrix24 import *
+from bitrix24 import Bitrix24
 
 bx24 = Bitrix24('https://example.bitrix24.com/rest/1/33olqeits4avuyqu')
 
 print(bx24.callMethod('crm.product.list'))
 ```
 
-## Advanced usage
-
-You can define filters and additional parameters in any order:
+In async mode:
 
 ```python
-bx24.callMethod('crm.deal.list',
-                order={'STAGE_ID': 'ASC'},
-                filter={'>PROBABILITY': 50},
-                select=['ID', 'TITLE', 'STAGE_ID', 'PROBABILITY'])
-```
+import asyncio
+from bitrix24 import bitrix24
 
-Catch the server error with exception:
+async def main():
+    bx24 = Bitrix24('https://example.bitrix24.com/rest/1/33olqeits4avuyqu')
+    result = await bx24.callMethod('crm.product.list')
+    print(result)
 
-```python
-try:
-    bx24.callMethod('tasks.task.add', fields={'TITLE': 'task for test', 'RESPONSIBLE_ID': 1})
-except BitrixError as message:
-    print(message)
+asyncio.run(main())
 ```
 
+## Advanced usage
+
+- [Using filters and additional parameters](docs/using-filters-and-additional-parameters.md)
+- [Working with large datasets](docs/working-with-large-datasets.md)
+- [Disabling certificate verification](docs/disabling-certificate-verification.md)
+
 ## Notes
-List methods return all available items at once. For large collections
-of data use limits.
 
-## Tests
+List methods return all available items at once. For large collections of data use limits.
 
+## Development
+
+New contributers and pull requests are welcome. If you have any questions or suggestions, feel free to open an issue.
+
+Code comes with makefile for easy code base management. You can check `make help` for more details.
+
+```sh
+make init install # to create a local virtual environment and install dependencies
+
+make test # to run tests
+
+make lint # to run linter
 ```
-python -m unittest discover
-```
 
-## Author
+I suggest to use `make all` before committing your changes as it will run all the necessary checks.
+
+## Support this project
 
-Akop Kesheshyan - <[email protected]>
+You can support this project by starring ⭐, sharing 📤, and contributing. 
 
-New contributers and pull requests are welcome.
+You can also support the author by buying him a coffee ☕. Click sponsor button on the top of the page.

docs/disabling-certificate-verification.md

@@ -0,0 +1,18 @@
+# Disabling certificate verification
+
+By default, the library verifies SSL certificates. If you want to disable this behavior, you can set `safe` parameter to `False` in the `Bitrix24` class.
+
+This tells Python's underlying SSL handling to accept the server's certificate even if it's expired or invalid.
+
+```python
+bx24 = Bitrix24('https://example.bitrix24.com/rest/1/33olqeits4avuyqu', safe=False)
+
+await bx24.callMethod('crm.deal.list')
+```
+
+## Important Consideration 
+
+Disabling SSL certificate verification undermines the security of HTTPS by making your application vulnerable to man-in-the-middle attacks. 
+
+It should only be used in controlled environments, such as development or testing, where security is not a concern.
+

docs/using-filters-and-additional-parameters.md

@@ -0,0 +1,26 @@
+# Using filters and additional parameters
+
+Define filters and additional parameters in any order using keyword arguments.
+
+```python
+bx24 = Bitrix24('https://example.bitrix24.com/rest/1/33olqeits4avuyqu')
+
+await bx24.callMethod('crm.deal.list',
+                order={'STAGE_ID': 'ASC'},
+                filter={'>PROBABILITY': 50},
+                select=['ID', 'TITLE', 'STAGE_ID', 'PROBABILITY'])
+```
+
+You also can pass filters as a dictionary, similar to the original Bitrix24 API:
+
+````python
+
+payload = {
+    'order': {'STAGE_ID': 'ASC'},
+    'filter': {'>PROBABILITY': 50},
+    'select': ['ID', 'TITLE', 'STAGE_ID', 'PROBABILITY']
+}
+
+await bx24.callMethod('crm.deal.list', payload)
+
+````

docs/working-with-large-datasets.md

@@ -0,0 +1,25 @@
+# Working with large datasets
+
+Fetching large datasets can be a problem. Bitrix24 REST API has a limit of 50 items per request and a rate limiter 
+that can block your requests if you exceed the limit. 
+
+This library has a built-in feature to handle large datasets without any hassle. 
+It will automatically detect if the dataset is paginated and fetch all the data at once.
+
+Also, all requests are made concurrently, which means you can fetch data faster and with low resource usage.
+
+However, if you for any reason want to disable this feature, you can do so by setting the `fetch_all_pages` parameter to `False`.
+
+
+```python
+
+bx24 = Bitrix24('https://example.bitrix24.com/rest/1/33olqeits4avuyqu', fetch_all_pages=False)
+
+# `page1` will contain only the first page of the dataset
+page1 = await bx24.callMethod('crm.deal.list')
+
+# fetch next page
+page2 = await bx24.callMethod('crm.deal.list', start=50)
+```
+
+In this mode, you will need to handle pagination manually.