enhance documentation

Author: akira-dev

README.rst

@@ -18,8 +18,8 @@ Install
 
     pip install Flask-REST-JSONAPI
 
-Quickstart
-==========
+A minimal api
+=============
 
 .. code-block:: python
 
@@ -37,36 +37,31 @@ Quickstart
     app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:////tmp/test.db'
     db = SQLAlchemy(app)
 
-
     # Create model
     class Person(db.Model):
         id = db.Column(db.Integer, primary_key=True)
-        name = db.Column(db.Unicode, unique=True)
-        birth_date = db.Column(db.Date)
+        name = db.Column(db.String)
 
     # Create the database.
     db.create_all()
 
-
     # Create schema
     class PersonSchema(Schema):
         class Meta:
             type_ = 'person'
             self_view = 'person_detail'
             self_view_kwargs = {'id': '<id>'}
+            self_view_many = 'person_list'
 
         id = fields.Str(dump_only=True)
         name = fields.Str()
-        birth_date = fields.Date()
 
-
-    # Create resource
+    # Create resource managers
     class PersonList(ResourceList):
         schema = PersonSchema
         data_layer = {'session': db.session,
                       'model': Person}
 
-
     class PersonDetail(ResourceDetail):
         schema = PersonSchema
         data_layer = {'session': db.session,

docs/data_layer.rst

@@ -5,4 +5,118 @@ Data layer
 
 .. currentmodule:: flask_rest_jsonapi
 
-Coming soon. If you want to learn let's see tests or api reference.
+| The data layer is a CRUD interface between resource manager and data. It is a very flexible system to use any ORM or data storage. You can even create a data layer that use multiple ORMs and data storage to manage your own objects. The data layer implements a CRUD interface for objects and relationships. It also manage pagination, filtering and sorting.
+|
+| Flask-REST-JSONAPI got a full featured data layer that use the popular ORM `SQLAlchemy <https://www.sqlalchemy.org/>`_.
+
+.. note::
+
+    The default data layer used by a resource manager is the SQLAlchemy one. So if you want to use it, you don't have to specify the class of the data layer in the resource manager
+
+To configure the data layer you have to set his required parameters in the resource manager.
+
+Example:
+
+.. code-block:: python
+
+    from flask_rest_jsonapi import ResourceList
+    from your_project.schemas import PersonSchema
+    from your_project.models import Person
+
+    class PersonList(ResourceList):
+        schema = PersonSchema
+        data_layer = {'session': db.session,
+                      'model': Person}
+
+You can also plug additional methods to your data layer in the resource manager. There is 2 kind of additional methods:
+* query: the "query" additional method takes view_kwargs as parameter and return an alternative query to retrieve the collection of objects in the get method of the ResourceList manager.
+* pre / post process methods: all CRUD and relationship(s) operations have a pre / post process methods. Thanks to it you can make additional work before and after each operations of the data layer. Parameters of each pre / post process methods are available in the `flask_rest_jsonapi.data_layers.base.Base <https://github.com/miLibris/flask-rest-jsonapi/blob/master/flask_rest_jsonapi/data_layers/base.py>`_ base class.
+
+Example:
+
+.. code-block:: python
+
+    from sqlalchemy.orm.exc import NoResultFound
+    from flask_rest_jsonapi import ResourceList
+    from flask_rest_jsonapi.exceptions import ObjectNotFound
+    from your_project.models import Computer, Person
+
+    class ComputerList(ResourceList):
+        def query(self, view_kwargs):
+            query_ = self.session.query(Computer)
+            if view_kwargs.get('id') is not None:
+                try:
+                    self.session.query(Person).filter_by(id=view_kwargs['id']).one()
+                except NoResultFound:
+                    raise ObjectNotFound({'parameter': 'id'}, "Person: {} not found".format(view_kwargs['id']))
+                else:
+                    query_ = query_.join(Person).filter(Person.id == view_kwargs['id'])
+            return query_
+
+        def before_create_object(self, data, view_kwargs):
+            if view_kwargs.get('id') is not None:
+                person = self.session.query(Person).filter_by(id=view_kwargs['id']).one()
+                data['person_id'] = person.id
+
+        schema = ComputerSchema
+        data_layer = {'session': db.session,
+                      'model': Computer,
+                      'methods': {'query': query,
+                                  'before_create_object': before_create_object}}
+
+.. note::
+
+    You don't have to declare additonals data layer methods in the resource manager. You can declare them in a dedicated module or in the declaration of the model.
+
+Example:
+
+.. code-block:: python
+
+    from sqlalchemy.orm.exc import NoResultFound
+    from flask_rest_jsonapi import ResourceList
+    from flask_rest_jsonapi.exceptions import ObjectNotFound
+    from your_project.models import Computer, Person
+    from your_project.additional_methods.computer import before_create_object
+
+    class ComputerList(ResourceList):
+        schema = ComputerSchema
+        data_layer = {'session': db.session,
+                      'model': Computer,
+                      'methods': {'query': Computer.query,
+                                  'before_create_object': before_create_object}}
+
+SQLAlchemy
+----------
+
+Required parameters:
+
+    :session: the session used by the data layer
+    :model: the model used by the data layer
+
+Optional parameters:
+
+    :id_field: the field used as identifier field instead of the primary key of the model
+    :url_field: the name of the parameter in the route to get value to filter with. Instead "id" is used.
+
+Custom data layer
+-----------------
+
+Like I said previously you can create and use your own data layer. A custom data layer must inherit from `flask_rest_jsonapi.data_layers.base.Base <https://github.com/miLibris/flask-rest-jsonapi/blob/master/flask_rest_jsonapi/data_layers/base.py>`_. You can see the full scope of possibilities of a data layer in this base class.
+
+Usage example:
+
+.. code-block:: python
+
+    from flask_rest_jsonapi import ResourceList
+    from your_project.schemas import PersonSchema
+    from your_project_data_layers import MyCustomDataLayer
+
+    class PersonList(ResourceList):
+        schema = PersonSchema
+        data_layer = {'class': MyCustomDataLayer,
+                      'param_1': value_1,
+                      'param_2': value_2}
+
+.. note::
+
+    All items except "class" in the data_layer dict of the resource manager will be plugged as instance attributes of the data layer. It is easier to use in the data layer.

docs/errors.rst

@@ -5,4 +5,77 @@ Errors
 
 .. currentmodule:: flask_rest_jsonapi
 
-Coming soon. If you want to learn let's see tests or api reference.
+JSONAPI 1.0 specification recommand to return errors like that:
+
+.. sourcecode:: http
+
+    HTTP/1.1 422 Unprocessable Entity
+    Content-Type: application/vnd.api+json
+
+    {
+      "errors": [
+        {
+          "status": "422",
+          "source": {
+            "pointer":"/data/attributes/first-name"
+          },
+          "title":  "Invalid Attribute",
+          "detail": "First name must contain at least three characters."
+        }
+      ],
+      "jsonapi": {
+        "version": "1.0"
+      }
+    }
+
+The "source" field gives information about the error if it is located in data provided or in querystring parameter.
+
+The previous example displays error located in data provided instead of this next example displays error located in querystring parameter "include":
+
+.. sourcecode:: http
+
+    HTTP/1.1 400 Bad Request
+    Content-Type: application/vnd.api+json
+
+    {
+      "errors": [
+        {
+          "status": "400",
+          "source": {
+            "parameter": "include"
+          },
+          "title":  "BadRequest",
+          "detail": "Include parameter is invalid"
+        }
+      ],
+      "jsonapi": {
+        "version": "1.0"
+      }
+    }
+
+Flask-REST-JSONAPI provides two kind of helpers to achieve error displaying:
+
+| * **the errors module**: you can import jsonapi_errors from the errors module to create the structure of a list of errors according to JSONAPI 1.0 specification
+|
+| * **the exceptions module**: you can import lot of exceptions from this module that helps you to raise exceptions that will be well formatted according to JSONAPI 1.0 specification
+
+When you create custom code for your api I recommand to use exceptions from exceptions module of Flask-REST-JSONAPI to raise errors because JsonApiException based exceptions are catched and rendered according to JSONAPI 1.0 specification.
+
+Example:
+
+.. code-block:: python
+
+    # all required imports are not displayed in this example
+    from flask_rest_jsonapi.exceptions import ObjectNotFound
+
+    class ComputerList(ResourceList):
+        def query(self, view_kwargs):
+            query_ = self.session.query(Computer)
+            if view_kwargs.get('id') is not None:
+                try:
+                    self.session.query(Person).filter_by(id=view_kwargs['id']).one()
+                except NoResultFound:
+                    raise ObjectNotFound({'parameter': 'id'}, "Person: {} not found".format(view_kwargs['id']))
+                else:
+                    query_ = query_.join(Person).filter(Person.id == view_kwargs['id'])
+            return query_

docs/filtering.rst

@@ -5,11 +5,11 @@ Filtering
 
 .. currentmodule:: flask_rest_jsonapi
 
-Flask-REST-JSONAPI as a very flexible filtering system. The filtering system is completely related to the data layer used by the resource. I will explain the filtering interface for SQLAlchemy data layer but you can use the same interface to your filtering implementation of your custom data layer. The only requirement is that you have to use the filter querystring parameter to make filtering according to JSONAPI 1.0 specification.
+Flask-REST-JSONAPI as a very flexible filtering system. The filtering system is completely related to the data layer used by the ResourceList manager. I will explain the filtering interface for SQLAlchemy data layer but you can use the same interface to your filtering implementation of your custom data layer. The only requirement is that you have to use the "filter" querystring parameter to make filtering according to JSONAPI 1.0 specification.
 
 .. note::
 
-    Urls examples are not urlencoded for a better readability
+    Examples are not urlencoded for a better readability
 
 SQLAlchemy
 ----------
@@ -27,7 +27,7 @@ In this example we want to retrieve persons which name is John. So we can see th
 
     :name: the name of the field you want to filter on
     :op: the operation you want to use (all sqlalchemy operations are available)
-    :val: the value that you want to compare. You can replace this by field if you want to compare against the value of an other field
+    :val: the value that you want to compare. You can replace this by "field" if you want to compare against the value of an other field
 
 Example with field:
 
@@ -57,7 +57,7 @@ If you want to filter through relationships you can do that:
 
 .. note ::
 
-    When you filter on relationships use "any" operator for to many relationships and "has" operator for to one relationships.
+    When you filter on relationships use "any" operator for "to many" relationships and "has" operator for "to one" relationships.
 
 There is a shortcut to achieve the same filter:
 
@@ -106,6 +106,8 @@ You can also use boolean combinaison of operations:
     ] HTTP/1.1
     Accept: application/vnd.api+json
 
+Availables operators depend on field type
+
 Common available operators:
 
 * any: used to filter on to many relationships
@@ -128,3 +130,7 @@ Common available operators:
 * notin_: check if field is not in a list of values
 * notlike: check if field does not contains a string
 * startswith: check if field starts with a string
+
+.. note::
+
+    Availables operators depend on field type in your model