From 006511683da0dd979e118cd265013c6136e154b6 Mon Sep 17 00:00:00 2001 From: Psy-Q Date: Tue, 2 Mar 2021 10:29:03 +0100 Subject: [PATCH 01/17] Revised grammar --- docs/configuration.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuration.rst b/docs/configuration.rst index 6c0d425..797c12b 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -6,7 +6,7 @@ Configuration You have access to 5 configration keys: * PAGE_SIZE: the number of items in a page (default is 30) -* MAX_PAGE_SIZE: the maximum page size. If you specify a page size greater than this value you will receive 400 Bad Request response. +* MAX_PAGE_SIZE: the maximum page size. If you specify a page size greater than this value you will receive a 400 Bad Request response. * MAX_INCLUDE_DEPTH: the maximum length of an include through schema relationships * ALLOW_DISABLE_PAGINATION: if you want to disallow to disable pagination you can set this configuration key to False -* CATCH_EXCEPTIONS: if you want flask_rest_jsonapi to catch all exceptions and return as JsonApiException (default is True) +* CATCH_EXCEPTIONS: if you want flask_rest_jsonapi to catch all exceptions and return them as JsonApiException (default is True) From b662553432023a68ca1b78fcc9f2eea7bfb82387 Mon Sep 17 00:00:00 2001 From: Psy-Q Date: Tue, 2 Mar 2021 10:37:17 +0100 Subject: [PATCH 02/17] Fix conjugations and grammar --- docs/data_layer.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/data_layer.rst b/docs/data_layer.rst index d01e951..0055b3e 100644 --- a/docs/data_layer.rst +++ b/docs/data_layer.rst @@ -5,13 +5,13 @@ Data layer .. currentmodule:: flask_rest_jsonapi -| 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. +| 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 uses multiple ORMs and data storage to manage your own objects. The data layer implements a CRUD interface for objects and relationships. It also manages pagination, filtering and sorting. | -| Flask-REST-JSONAPI has a full featured data layer that use the popular ORM `SQLAlchemy `_. +| Flask-REST-JSONAPI has a full-featured data layer that uses the popular ORM `SQLAlchemy `_. .. 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 + The default data layer used by a resource manager is the SQLAlchemy one. So if that's what you want to use, 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 its required parameters in the resource manager. @@ -28,11 +28,11 @@ Example: data_layer = {'session': db.session, 'model': Person} -You can also plug additional methods to your data layer in the resource manager. There are two kinds of additional methods: +You can also plug additional methods into your data layer in the resource manager. There are two kinds 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. +* query: the "query" additional method takes view_kwargs as parameter and returns 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 `_ base class. +* pre-/postprocess methods: all CRUD and relationship(s) operations have pre-/postprocess methods. Thanks to these you can do additional work before and after each operation of the data layer. Parameters of each pre-/postprocess method are available in the `flask_rest_jsonapi.data_layers.base.Base `_ base class. Example: @@ -68,7 +68,7 @@ Example: .. note:: - You don't have to declare additional data layer methods in the resource manager. You can declare them in a dedicated module or in the declaration of the model. + You don't have to declare additional data layer methods in the resource manager. You can declare them in a dedicated module or in the model's declaration. Example: @@ -100,12 +100,12 @@ 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. -By default SQLAlchemy eagerload related data specified in include querystring parameter. If you want to disable this feature you must add eagerload_includes: False to data layer parameters. +By default SQLAlchemy eagerly loads related data specified in the include query string parameter. If you want to disable this feature you must add eagerload_includes: False to the data layer parameters. 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 `_. You can see the full scope of possibilities of a data layer in this base class. +As previously mentioned, you can create and use your own data layer. A custom data layer must inherit from `flask_rest_jsonapi.data_layers.base.Base `_. You can see the full scope of possibilities of a data layer in this base class. Usage example: From 1a24e5ab4db7ac7d6a7fa988f3a7fdbe65d3ad87 Mon Sep 17 00:00:00 2001 From: Psy-Q Date: Tue, 2 Mar 2021 10:41:15 +0100 Subject: [PATCH 03/17] Fix conjugations, grammar, JSONAPI -> JSON:API --- docs/errors.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/errors.rst b/docs/errors.rst index e5c608b..2487110 100644 --- a/docs/errors.rst +++ b/docs/errors.rst @@ -5,7 +5,7 @@ Errors .. currentmodule:: flask_rest_jsonapi -JSONAPI 1.0 specification recommend to return errors like that: +The JSON:API 1.0 specification recommends to return errors like this: .. sourcecode:: http @@ -28,9 +28,9 @@ JSONAPI 1.0 specification recommend to return errors like that: } } -The "source" field gives information about the error if it is located in data provided or in querystring parameter. +The "source" field gives information about the error if it is located in data provided or in a query string parameter. -The previous example displays error located in data provided instead of this next example displays error located in querystring parameter "include": +The previous example shows an error located in data provided. The following example shows error in the query string parameter "include": .. sourcecode:: http @@ -53,13 +53,13 @@ The previous example displays error located in data provided instead of this nex } } -Flask-REST-JSONAPI provides two kind of helpers to achieve error displaying: +Flask-REST-JSONAPI provides two kinds of helpers for displaying errors: | * **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 +| * **the exceptions module**: you can import a lot of exceptions from this `module `_ that helps you to raise exceptions that will be well-formatted according to the JSON:API 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. +When you create custom code for your API I recommand using exceptions from the Flask-REST-JSONAPI's exceptions module to raise errors because JsonApiException-based exceptions are caught and rendered according to the JSON:API 1.0 specification. Example: From 4a4cbe6f188b44f2f045afd3df67ff8790b3588d Mon Sep 17 00:00:00 2001 From: Psy-Q Date: Tue, 2 Mar 2021 10:51:48 +0100 Subject: [PATCH 04/17] Fix conjugations, grammar, sqlalchemy -> SQLAlchemy --- docs/filtering.rst | 66 +++++++++++++++++++++++----------------------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/docs/filtering.rst b/docs/filtering.rst index 426021f..ed9f35a 100644 --- a/docs/filtering.rst +++ b/docs/filtering.rst @@ -5,7 +5,7 @@ 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 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 the JSONAPI 1.0 specification. +Flask-REST-JSONAPI has a very flexible filtering system. The filtering system is directly attached to the data layer used by the ResourceList manager. These examples show the filtering interface for SQLAlchemy's data layer but you can use the same interface for your custom data layer's filtering implementation as well. The only requirement is that you have to use the "filter" query string parameter to filter according to the JSON:API 1.0 specification. .. note:: @@ -14,7 +14,7 @@ Flask-REST-JSONAPI as a very flexible filtering system. The filtering system is SQLAlchemy ---------- -The filtering system of SQLAlchemy data layer has exactly the same interface as the filtering system of `Flask-Restless `_. +The filtering system of SQLAlchemy's data layer has exactly the same interface as the one used in `Flask-Restless `_. So this is a first example: .. sourcecode:: http @@ -22,11 +22,11 @@ So this is a first example: GET /persons?filter=[{"name":"name","op":"eq","val":"John"}] HTTP/1.1 Accept: application/vnd.api+json -In this example we want to retrieve persons which name is John. So we can see that the filtering interface completely fit the filtering interface of SQLAlchemy: a list a filter information. +In this example we want to retrieve person records for people named John. So we can see that the filtering interface completely fits that of SQLAlchemy: a list a filter information. :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 + :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 another field Example with field: @@ -35,7 +35,7 @@ Example with field: GET /persons?filter=[{"name":"name","op":"eq","field":"birth_date"}] HTTP/1.1 Accept: application/vnd.api+json -In this example, we want to retrieve persons that name is equal to his birth_date. I know, this example is absurd but it is just to explain the syntax of this kind of filter. +In this example, we want to retrieve people whose name is equal to their birth_date. This example is absurd, it's just here to explain the syntax of this kind of filter. If you want to filter through relationships you can do that: @@ -56,9 +56,9 @@ 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 the "any" operator for "to many" relationships and the "has" operator for "to one" relationships. -There is a shortcut to achieve the same filter: +There is a shortcut to achieve the same filtering: .. sourcecode:: http @@ -105,36 +105,36 @@ You can also use boolean combination of operations: Common available operators: -* any: used to filter on to many relationships +* any: used to filter on "to many" relationships * between: used to filter a field between two values -* endswith: check if field ends with a string -* eq: check if field is equal to something -* ge: check if field is greater than or equal to something -* gt: check if field is greater than to something -* has: used to filter on to one relationships -* ilike: check if field contains a string (case insensitive) -* in\_: check if field is in a list of values -* is\_: check if field is a value -* isnot: check if field is not a value -* like: check if field contains a string -* le: check if field is less than or equal to something -* lt: check if field is less than to something -* match: check if field match against a string or pattern -* ne: check if field is not equal to something -* notilike: check if field does not contains a string (case insensitive) -* 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 +* endswith: checks if field ends with a string +* eq: checks if field is equal to something +* ge: checks if field is greater than or equal to something +* gt: checks if field is greater than something +* has: used to filter on "to one" relationships +* ilike: checks if field contains a string (case insensitive) +* in\_: checks if field is in a list of values +* is\_: checks if field is a value +* isnot: checks if field is not a value +* like: checks if field contains a string +* le: checks if field is less than or equal to something +* lt: checks if field is less than something +* match: checks if field matches against a string or pattern +* ne: checks if field is not equal to something +* notilike: checks if field does not contain a string (case insensitive) +* notin\_: checks if field is not in a list of values +* notlike: checks if field does not contain a string +* startswith: checks if field starts with a string .. note:: - Availables operators depend on field type in your model + Available operators depend on the field type in your model Simple filters -------------- -Simple filter adds support for a simplified form of filters and supports only *eq* operator. -Each simple filter transforms to original filter and appends to list of filters. +Simple filters add support for a simplified form of filters and support only the *eq* operator. +Each simple filter is transformed into a full filter and appended to the list of filters. For example @@ -143,7 +143,7 @@ For example GET /persons?filter[name]=John HTTP/1.1 Accept: application/vnd.api+json -equals to: +equals: .. sourcecode:: http @@ -151,14 +151,14 @@ equals to: Accept: application/vnd.api+json -You can also use more than one simple filter in request: +You can also use more than one simple filter in a request: .. sourcecode:: http GET /persons?filter[name]=John&filter[gender]=male HTTP/1.1 Accept: application/vnd.api+json -which equals to: +which is equal to: .. sourcecode:: http From a81316bc8df8440e7f1998e215ecd1b9a100c081 Mon Sep 17 00:00:00 2001 From: Psy-Q Date: Tue, 2 Mar 2021 10:53:55 +0100 Subject: [PATCH 05/17] Fix conjugations and grammar --- docs/include_related_objects.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/include_related_objects.rst b/docs/include_related_objects.rst index fe75d64..31c2b98 100644 --- a/docs/include_related_objects.rst +++ b/docs/include_related_objects.rst @@ -5,9 +5,9 @@ Include related objects .. currentmodule:: flask_rest_jsonapi -You can include related object(s) details to responses with the querystring parameter named "include". You can use "include" parameter on any kind of route (classical CRUD route or relationships route) and any kind of http methods as long as method return data. +You can include related object(s) details in responses with the query string parameter named "include". You can use the "include" parameter on any kind of route (classical CRUD route or relationships route) and any kind of HTTP methods as long as the method returns data. -This features will add an additional key in result named "included" +This feature will add an additional key in the result named "included" Example: @@ -174,4 +174,4 @@ Response: } } -I know it is an absurd example because it will include details of related person computers and details of the person that is already in the response. But it is just for example. +It's an absurd example because it will include details of the related person's computers and details of the person that is already in the response. But it is just for demonstration. From f26c3339e85ff6f7ee0c20bf9d26382ff61f7f89 Mon Sep 17 00:00:00 2001 From: Psy-Q Date: Tue, 2 Mar 2021 11:00:03 +0100 Subject: [PATCH 06/17] Fix grammar, phrasing --- docs/index.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 9dfee51..a1378b2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,7 +3,7 @@ Flask-REST-JSONAPI .. module:: flask_rest_jsonapi -**Flask-REST-JSONAPI** is an extension for Flask that adds support for quickly building REST APIs with huge flexibility around the JSONAPI 1.0 specification. It is designed to fit the complexity of real life environments so Flask-REST-JSONAPI helps you to create a logical abstraction of your data called "resource" and can interface any kind of ORMs or data storage through data layer concept. +**Flask-REST-JSONAPI** is an extension for Flask that adds support for quickly building REST APIs with huge flexibility around the JSON:API 1.0 specification. It is designed to fit the complexity of real life environments so Flask-REST-JSONAPI helps you to create a logical abstraction of your data called "resource". It can interface any kind of ORMs or data storage through the conept of data layers. Main concepts ------------- @@ -12,16 +12,16 @@ Main concepts :width: 900px :alt: Architecture -| * `JSON API 1.0 specification `_: it is a very popular specification about client server interactions for REST JSON API. It helps you work in a team because it is very precise and sharable. Thanks to this specification your API offers lots of features like a strong structure of request and response, filtering, pagination, sparse fieldsets, including related objects, great error formatting etc. +| * `JSON:API 1.0 specification `_: this is a very popular specification for client-server interactions through a JSON-based REST API. It helps you work in a team because it is very precise and sharable. Thanks to this specification your API can offer a lot of features such as a strong structure of request and response, filtering, pagination, sparse fieldsets, including related objects, great error formatting, etc. | -| * **Logical data abstraction**: you usually need to expose resources to clients that don't fit your data table architecture. For example sometimes you don't want to expose all attributes of a table, compute additional attributes or create a resource that uses data from multiple data storages. Flask-REST-JSONAPI helps you create a logical abstraction of your data with `Marshmallow `_ / `marshmallow-jsonapi `_ so you can expose your data through a very flexible way. +| * **Logical data abstraction**: you usually need to expose resources to clients that don't fit your data table architecture. For example sometimes you don't want to expose all attributes of a table, compute additional attributes or create a resource that uses data from multiple data storages. Flask-REST-JSONAPI helps you create a logical abstraction of your data with `Marshmallow `_ / `marshmallow-jsonapi `_ so you can expose your data in a very flexible way. | -| * **Data layer**: the data layer is a CRUD interface between your resource manager and your data. Thanks to it you can use any data storage or ORMs. There is an already full featured data layer that uses the SQLAlchemy ORM but you can create and use your own custom data layer to use data from your data storage(s). You can even create a data layer that uses multiple data storages and ORMs, send notifications or make any custom work during CRUD operations. +| * **Data layer**: the data layer is a CRUD interface between your resource manager and your data. Thanks to this you can use any data storage or ORM. There is an already full-featured data layer that uses the SQLAlchemy ORM but you can create and use your own custom data layer to use data from your data storage. You can even create a data layer that uses multiple data storage systems and ORMs, send notifications or perform custom actions during CRUD operations. Features -------- -Flask-REST-JSONAPI has lots of features: +Flask-REST-JSONAPI has many features: * Relationship management * Powerful filtering @@ -36,7 +36,7 @@ Flask-REST-JSONAPI has lots of features: User's Guide ------------ -This part of the documentation will show you how to get started in using +This part of the documentation will show you how to get started using Flask-REST-JSONAPI with Flask. .. toctree:: From c0022b58af6be2d63d33813564629c7156ace445 Mon Sep 17 00:00:00 2001 From: Psy-Q Date: Tue, 2 Mar 2021 11:00:46 +0100 Subject: [PATCH 07/17] Fix grammar --- docs/installation.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index 9e590c0..8a246fe 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -20,9 +20,9 @@ The development version can be downloaded from `its page at GitHub .. note:: - If you don't have virtualenv please install it before + If you don't have virtualenv please install it $ pip install virtualenv -Flask-RESTful requires Python version 2.7, 3.4 or 3.5. \ No newline at end of file +Flask-RESTful requires Python version 2.7, 3.4 or 3.5. From 8764b0e992fbd3afa00508d0c7fa40579ae7e5c0 Mon Sep 17 00:00:00 2001 From: Psy-Q Date: Tue, 2 Mar 2021 11:04:50 +0100 Subject: [PATCH 08/17] Fix grammar --- docs/logical_data_abstraction.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/logical_data_abstraction.rst b/docs/logical_data_abstraction.rst index 100207b..7371f36 100644 --- a/docs/logical_data_abstraction.rst +++ b/docs/logical_data_abstraction.rst @@ -5,11 +5,11 @@ Logical data abstraction .. currentmodule:: flask_rest_jsonapi -The first thing to do in Flask-REST-JSONAPI is to create a logical data abstraction. This part of the api discribes schemas of resources exposed by the api that is not the exact mapping of the data architecture. The declaration of schemas is made by `Marshmallow `_ / `marshmallow-jsonapi `_. Marshmallow is a very popular serialization / deserialization library that offers a lot of features to abstract your data architecture. Moreover there is an other library called marshmallow-jsonapi that fit the JSONAPI 1.0 specification and provides Flask integration. +The first thing to do in Flask-REST-JSONAPI is to create a logical data abstraction. This part of the API describes schemas of resources exposed by the API that are not an exact mapping of the data architecture. The declaration of schemas is performed by `Marshmallow `_ / `marshmallow-jsonapi `_. Marshmallow is a very popular serialization/deserialization library that offers a lot of features to abstract your data architecture. Moreover there is another library called marshmallow-jsonapi that fits the JSON:API 1.0 specification and provides Flask integration. Example: -In this example, let's assume that we have 2 legacy models Person and Computer, and we want to create an abstraction over them. +In this example, let's assume that we have two legacy models, Person and Computer, and we want to create an abstraction on top of them. .. code-block:: python @@ -76,17 +76,17 @@ Now let's create the logical abstraction to illustrate this concept. schema='PersonSchema', type_='person') -You can see several differences between models and schemas exposed by the api. +You can see several differences between models and schemas exposed by the API. First, take a look at the Person compared to PersonSchema: -* we can see that Person has an attribute named "password" and we don't want to expose it through the api so it is not set in PersonSchema +* We can see that Person has an attribute named "password" and we don't want to expose it through the api so it is not set in PersonSchema * PersonSchema has an attribute named "display_name" that is the result of concatenation of name and email -* In the computers Relationship() defined on PersonSchema we have set the id_field to "computer_id" as that is the primary key on the Computer(db.model). Without setting id_field the relationship looks for a field called "id". +* In the "computers" Relationship() defined on PersonSchema we have set the id_field to "computer_id" as that is the primary key on the Computer(db.model). Without setting id_field the relationship looks for a field called "id". Second, take a look at the Computer compared to ComputerSchema: -* we can see that the attribute computer_id is exposed as id for consistency of the api -* we can see that the person relationship between Computer and Person is exposed in ComputerSchema as owner because it is more explicit +* The attribute computer_id is exposed as id for consistency of the api +* The person relationship between Computer and Person is exposed in ComputerSchema as owner because it is more explicit -As a result you can see that you can expose your data in a very flexible way to create the api of your choice over your data architecture. +As a result you can see that you can expose your data in a very flexible way to create the API of your choice on top of your data architecture. From 89211d4b1579954ee22d59d51393ee6bcebf8755 Mon Sep 17 00:00:00 2001 From: Psy-Q Date: Tue, 2 Mar 2021 11:06:53 +0100 Subject: [PATCH 09/17] Fix grammar --- docs/oauth.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/oauth.rst b/docs/oauth.rst index d996d6c..0627fdd 100644 --- a/docs/oauth.rst +++ b/docs/oauth.rst @@ -5,7 +5,7 @@ OAuth .. currentmodule:: flask_rest_jsonapi -Flask-REST-JSONAPI support OAuth via `Flask-OAuthlib `_ +Flask-REST-JSONAPI supports OAuth via `Flask-OAuthlib `_ Example: @@ -27,7 +27,7 @@ In this example Flask-REST-JSONAPI will protect all your resource methods with t oauth2.require_oauth() -The pattern of the scope is like that :: +The pattern of the scope is :: _ @@ -43,7 +43,7 @@ Example :: list_person -If you want to customize the scope you can provide a function that computes your custom scope. The function have to looks like that: +If you want to customize the scope you can provide a function that computes your custom scope. The function has to look like this: .. code-block:: python @@ -74,9 +74,9 @@ Usage example: .. note:: - You can name the custom scope computation method as you want but you have to set the 2 required parameters: resource and method like in this previous example. + You can name the custom scope computation method as you want but you have to set the two required parameters "resource" and "method" as in this previous example. -If you want to disable OAuth or make custom methods protection for a resource you can add this option to the resource manager. +If you want to disable OAuth or create custom method protection for a resource you can add this option to the resource manager. Example: From 25a7aaa22a56186be097405cc87f5efa78574c20 Mon Sep 17 00:00:00 2001 From: Psy-Q Date: Tue, 2 Mar 2021 11:07:08 +0100 Subject: [PATCH 10/17] Fix ortography --- docs/oauth.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/oauth.rst b/docs/oauth.rst index 0627fdd..e75fa30 100644 --- a/docs/oauth.rst +++ b/docs/oauth.rst @@ -90,4 +90,4 @@ Example: @oauth2.require_oauth('custom_scope') def get(*args, **kwargs): - return 'Hello world !' + return 'Hello world!' From 1a48d67700dad58b2b8b76243d3bac4bbded0c1a Mon Sep 17 00:00:00 2001 From: Psy-Q Date: Tue, 2 Mar 2021 11:10:06 +0100 Subject: [PATCH 11/17] Fix grammar --- docs/pagination.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/pagination.rst b/docs/pagination.rst index 552f6d4..aa395d8 100644 --- a/docs/pagination.rst +++ b/docs/pagination.rst @@ -5,16 +5,16 @@ Pagination .. currentmodule:: flask_rest_jsonapi -When you use the default implementation of get method on a ResourceList your results will be paginated by default. Default pagination size is 30 but you can manage it from querystring parameter named "page". +When you use the default implementation of the get method on a ResourceList your results will be paginated by default. Default pagination size is 30 but you can manage it from querystring parameter named "page". .. note:: - Examples are not urlencoded for a better readability + Examples are not URL encoded for a better readability Size ---- -You can control page size like that: +You can control page size like this: .. sourcecode:: http @@ -24,7 +24,7 @@ You can control page size like that: Number ------ -You can control page number like that: +You can control page number like this: .. sourcecode:: http @@ -34,7 +34,7 @@ You can control page number like that: Size + Number ------------- -Of course, you can control both like that: +Of course, you can control both like this: .. sourcecode:: http @@ -44,7 +44,7 @@ Of course, you can control both like that: Disable pagination ------------------ -You can disable pagination with size = 0 +You can disable pagination by setting size to 0 .. sourcecode:: http From b718943fdaf184837232ec72a809f97da0232eb2 Mon Sep 17 00:00:00 2001 From: Psy-Q Date: Tue, 2 Mar 2021 11:14:56 +0100 Subject: [PATCH 12/17] Fix grammar and phrasing --- docs/permission.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/permission.rst b/docs/permission.rst index d69f48e..1378bc9 100644 --- a/docs/permission.rst +++ b/docs/permission.rst @@ -5,7 +5,7 @@ Permission .. currentmodule:: flask_rest_jsonapi -Flask-REST-JSONAPI provides a very agnostic permission system. +Flask-REST-JSONAPI provides an agnostic permission system. Example: @@ -23,7 +23,7 @@ Example: In this previous example, the API will check permission before each method call with the permission_manager function. -The permission manager must be a function that looks like this: +The permission_manager must be a function that looks like this: .. code-block:: python @@ -39,9 +39,9 @@ The permission manager must be a function that looks like this: .. note:: - Flask-REST-JSONAPI use a decorator to check permission for each method named has_permission. You can provide args and kwargs to this decorators so you can retrieve this args and kwargs in the permission_manager. The default usage of the permission system does not provides any args or kwargs to the decorator. + Flask-REST-JSONAPI uses a decorator named has_permission to check permission for each method. You can provide args and kwargs to this decorator so you can retrieve them in the permission_manager. The default usage of the permission system does not provide any args or kwargs to the decorator. -If permission is denied I recommend to raise exception like that: +If permission is denied, raising an exception is recommended: .. code-block:: python @@ -50,7 +50,7 @@ If permission is denied I recommend to raise exception like that: title='Permission denied', status='403') -You can disable the permission system or make custom permission checking management of a resource like that: +You can disable the permission system or create custom permission checking of a resource like this: .. code-block:: python @@ -66,7 +66,7 @@ You can disable the permission system or make custom permission checking managem .. warning:: - If you want to use both permission system and oauth support to retrieve information like user from oauth (request.oauth.user) in the permission system you have to initialize permission system before to initialize oauth support because of decorators cascading. + If you want to use both the permission system and OAuth support to retrieve information such as a user (request.oauth.user), you have to initialize the permission system before initializing OAuth support. This is because of decorator cascading. Example: From fd60b07e7859137a8cfd9a00b093144aeaedccdd Mon Sep 17 00:00:00 2001 From: Psy-Q Date: Tue, 2 Mar 2021 11:20:56 +0100 Subject: [PATCH 13/17] Fix grammar --- docs/quickstart.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index f313413..3a14eb3 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -7,7 +7,7 @@ Quickstart It's time to write your first REST API. This guide assumes you have a working understanding of `Flask `_, and that you have already installed both Flask and Flask-REST-JSONAPI. If not, then follow the steps in the :ref:`installation` section. -In this section you will learn basic usage of Flask-REST-JSONAPI around a small tutorial that use the SQLAlchemy data layer. This tutorial show you an example of a person and his computers. +In this section you will learn basic usage of Flask-REST-JSONAPI around a small tutorial that uses the SQLAlchemy data layer. This tutorial shows you an example of a person and their computers. First example ------------- @@ -175,7 +175,7 @@ An example of Flask-REST-JSONAPI API looks like this: # Start application app.run(debug=True) -This example provides this api: +This example provides the following API: +------------------------------------------+--------+------------------+-------------------------------------------------------+ | url | method | endpoint | action | @@ -229,7 +229,7 @@ This example provides this api: .. warning:: - In this example, I use Flask-SQLAlchemy so you have to install it before to run the example. + In this example, I use Flask-SQLAlchemy so you have to install it before running the example. $ pip install flask_sqlalchemy @@ -435,12 +435,12 @@ Response: Relationships ------------- -| Now let's use relationships tools. First, create 3 computers named Halo, Nestor and Comodor like in previous example. +| Now let's use some relationship tools. First, create three computers named Halo, Nestor and Commodore like in the previous example. | -| Done ? +| Done? | Ok. So let's continue this tutorial. | -| We assume that Halo has id: 2, Nestor id: 3 and Comodor has id: 4. +| We assume that Halo has id: 2, Nestor id: 3 and Commodore has id: 4. Create object with related object(s) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -535,18 +535,18 @@ Response: } } -You can see that I have added the querystring parameter "include" to the url +You can see that we have added the query string parameter "include" to the URL .. sourcecode:: http POST /persons?include=computers HTTP/1.1 -Thanks to this parameter, related computers details are included to the result. If you want to learn more: :ref:`include_related_objects` +Thanks to this parameter, the related computers' details are included in the result. If you want to learn more: :ref:`include_related_objects` Update object and his relationships ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Now John sell his Amstrad and buy a new computer named Nestor (id: 3). So we want to link this new computer to John. John have also made a mistake in his birth_date so let's update this 2 things in the same time. +Now John sell his Amstrad and buy a new computer named Nestor (id: 3). So we want to link this new computer to John. John also made a mistake in his birth_date so let's update these two things at the same time. Request: @@ -640,7 +640,7 @@ Response: Create relationship ~~~~~~~~~~~~~~~~~~~ -Now John buy a new computer named Comodor so let's link it to John. +Now John buys a new computer named Commodore so let's link it to John. Request: @@ -719,7 +719,7 @@ Response: "type": "computer", "id": "4", "attributes": { - "serial": "Comodor" + "serial": "Commodore" }, "relationships": { "owner": { @@ -746,7 +746,7 @@ Response: Delete relationship ~~~~~~~~~~~~~~~~~~~ -Now John sell his old Nestor computer so let's unlink it from John. +Now John sells his old Nestor computer, so let's unlink it from John. Request: @@ -803,7 +803,7 @@ Response: "type": "computer", "id": "4", "attributes": { - "serial": "Comodor" + "serial": "Commodore" }, "relationships": { "owner": { @@ -826,4 +826,4 @@ Response: } } -If you want to see more examples go to `JSON API 1.0 specification `_ +For more examples see the `JSON:API 1.0 specification `_ From ddb3450e9727d5cb40d6104768f5ddcd7f2bd360 Mon Sep 17 00:00:00 2001 From: Psy-Q Date: Tue, 2 Mar 2021 11:29:39 +0100 Subject: [PATCH 14/17] Fix grammar --- docs/resource_manager.rst | 48 +++++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/resource_manager.rst b/docs/resource_manager.rst index 3afe864..1fcfdc8 100644 --- a/docs/resource_manager.rst +++ b/docs/resource_manager.rst @@ -7,18 +7,18 @@ Resource Manager Resource manager is the link between your logical data abstraction, your data layer and optionally other software. It is the place where logic management of your resource is located. -Flask-REST-JSONAPI provides 3 kinds of resource manager with default methods implementation according to the JSONAPI 1.0 specification: +Flask-REST-JSONAPI provides three kinds of resource managers with default methods implemented according to the JSON:API 1.0 specification: -* **ResourceList**: provides get and post methods to retrieve a collection of objects or create one. -* **ResourceDetail**: provides get, patch and delete methods to retrieve details of an object, update an object and delete an object -* **ResourceRelationship**: provides get, post, patch and delete methods to get relationships, create relationships, update relationships and delete relationships between objects. +* **ResourceList**: provides get and post methods to retrieve or create a collection of objects. +* **ResourceDetail**: provides get, patch and delete methods to retrieve details of an object, update or delete it +* **ResourceRelationship**: provides get, post, patch and delete methods to get, create, update and delete relationships between objects. -You can rewrite each default methods implementation to make custom work. If you rewrite all default methods implementation of a resource manager or if you rewrite a method and disable access to others, you don't have to set any attribute of your resource manager. +You can rewrite each default method implementation to customize it. If you rewrite all default methods of a resource manager or if you rewrite a method and disable access to others, you don't have to set any attributes of your resource manager. Required attributes ------------------- -If you want to use one of the resource manager default method implementation you have to set 2 required attributes in your resource manager: schema and data_layer. +If you want to use one of the resource manager default method implementations you have to set two required attributes in your resource manager: schema and data_layer. :schema: the logical data abstraction used by the resource manager. It must be a class inherited from marshmallow_jsonapi.schema.Schema. :data_layer: data layer information used to initialize your data layer (If you want to learn more: :ref:`data_layer`) @@ -40,28 +40,28 @@ Example: Optional attributes ------------------- -All resource managers are inherited from flask.views.MethodView so you can provides optional attributes to your resource manager: +All resource managers are inherited from flask.views.MethodView so you can provide optional attributes to your resource manager: :methods: a list of methods this resource manager can handle. If you don't specify any method, all methods are handled. - :decorators: a tuple of decorators plugged to all methods that the resource manager can handle + :decorators: a tuple of decorators plugged into all methods that the resource manager can handle -You can provide default schema kwargs for each resource manager methods with these optional attributes: +You can provide default schema kwargs for each resource manager method with these optional attributes: * **get_schema_kwargs**: a dict of default schema kwargs in get method * **post_schema_kwargs**: a dict of default schema kwargs in post method * **patch_schema_kwargs**: a dict of default schema kwargs in patch method * **delete_schema_kwargs**: a dict of default schema kwargs in delete method -Each method of a resource manager gets a pre and post process methods that takes view args and kwargs as parameters for the pre process methods, and the result of the method as parameter for the post process method. Thanks to this you can make custom work before and after the method process. Available methods to override are: +Each method of a resource manager gets a pre- and postprocess method that takes view args and kwargs as parameters for the pre process methods, and the result of the method as parameter for the post process method. Thanks to this you can process custom code before and after the method processes. Available methods to override are: - :before_get: pre process method of the get method - :after_get: post process method of the get method - :before_post: pre process method of the post method - :after_post: post process method of the post method - :before_patch: pre process method of the patch method - :after_patch: post process method of the patch method - :before_delete: pre process method of the delete method - :after_delete: post process method of the delete method + :before_get: preprocess method of the get method + :after_get: postprocess method of the get method + :before_post: preprocess method of the post method + :after_post: postprocess method of the post method + :before_patch: preprocess method of the patch method + :after_patch: postprocess method of the patch method + :before_delete: preprocess method of the delete method + :after_delete: postprocess method of the delete method Example: @@ -82,11 +82,11 @@ Example: get_schema_kwargs = {'only': ('name', )} def before_patch(*args, **kwargs): - """Make custom work here. View args and kwargs are provided as parameter + """Perform custom operations here. View args and kwargs are provided as parameter """ def after_patch(result): - """Make custom work here. Add something to the result of the view. + """Perform custom operations here. Add something to the result of the view. """ ResourceList @@ -94,7 +94,7 @@ ResourceList ResourceList manager has its own optional attributes: - :view_kwargs: if you set this flag to True view kwargs will be used to compute the list url. If you have a list url pattern with parameter like that: /persons//computers you have to set this flag to True + :view_kwargs: if you set this flag to True, view kwargs will be used to compute the list URL. If you have a list URL pattern with parameters such as ``/persons//computers`` you have to set this flag to True Example: @@ -131,9 +131,9 @@ Example: data_layer = {'session': db.session, 'model': Person} -This minimal ResourceDetail configuration provides GET, PATCH and DELETE interface to retrieve details of objects, update an objects and delete an object with all powerful features like sparse fieldsets and including related objects. +This minimal ResourceDetail configuration provides a GET, PATCH and DELETE interface to retrieve details of an object, update and delete it with all-powerful features like sparse fieldsets and including related objects. -If your schema has relationship field(s) you can update an object and also update his link(s) to related object(s) in the same time. For an example see :ref:`quickstart`. +If your schema has relationship fields you can update an object and also update its links to (one or more) related objects at the same time. For an example see :ref:`quickstart`. ResourceRelationship -------------------- @@ -152,4 +152,4 @@ Example: data_layer = {'session': db.session, 'model': Person} -This minimal ResourceRelationship configuration provides GET, POST, PATCH and DELETE interface to retrieve relationship(s), create relationship(s), update relationship(s) and delete relationship(s) between objects with all powerful features like sparse fieldsets and including related objects. +This minimal ResourceRelationship configuration provides a GET, POST, PATCH and DELETE interface to retrieve, create, update or delete one or more relationships between objects with all-powerful features like sparse fieldsets and including related objects. From 3158c1fda996d12528fba1b79ea1825458fa6341 Mon Sep 17 00:00:00 2001 From: Psy-Q Date: Tue, 2 Mar 2021 11:31:05 +0100 Subject: [PATCH 15/17] Fix grammar --- docs/sorting.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/sorting.rst b/docs/sorting.rst index 51e556d..bdd2e18 100644 --- a/docs/sorting.rst +++ b/docs/sorting.rst @@ -5,11 +5,11 @@ Sorting .. currentmodule:: flask_rest_jsonapi -You can sort results with querystring parameter named "sort" +You can sort results using the query string parameter named "sort" .. note:: - Examples are not urlencoded for a better readability + Examples are not URL encoded for better readability Example: @@ -21,7 +21,7 @@ Example: Multiple sort ------------- -You can sort on multiple fields like that: +You can sort on multiple fields like this: .. sourcecode:: http @@ -31,7 +31,7 @@ You can sort on multiple fields like that: Descending sort --------------- -You can make desc sort with the character "-" like that: +You can in descendin gorder using a minus symbol, "-", like this: .. sourcecode:: http @@ -41,7 +41,7 @@ You can make desc sort with the character "-" like that: Multiple sort + Descending sort ------------------------------- -Of course, you can combine both like that: +Of course, you can combine both like this: .. sourcecode:: http From 60aba2681a84dd696188fa3a39802b6fd1f6530e Mon Sep 17 00:00:00 2001 From: Psy-Q Date: Tue, 2 Mar 2021 11:31:19 +0100 Subject: [PATCH 16/17] Fix typo --- docs/sorting.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sorting.rst b/docs/sorting.rst index bdd2e18..6faa80b 100644 --- a/docs/sorting.rst +++ b/docs/sorting.rst @@ -31,7 +31,7 @@ You can sort on multiple fields like this: Descending sort --------------- -You can in descendin gorder using a minus symbol, "-", like this: +You can in descending order using a minus symbol, "-", like this: .. sourcecode:: http From bdfa4305eb921c7f55cc2fa08a239e25b5b77c9d Mon Sep 17 00:00:00 2001 From: Psy-Q Date: Tue, 2 Mar 2021 11:34:00 +0100 Subject: [PATCH 17/17] Fix grammar --- docs/sparse_fieldsets.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/sparse_fieldsets.rst b/docs/sparse_fieldsets.rst index 5f8b849..60aacdc 100644 --- a/docs/sparse_fieldsets.rst +++ b/docs/sparse_fieldsets.rst @@ -5,13 +5,13 @@ Sparse fieldsets .. currentmodule:: flask_rest_jsonapi -You can restrict the fields returned by api with the querystring parameter called "fields". It is very useful for performance purpose because fields not returned are not resolved by api. You can use "fields" parameter on any kind of route (classical CRUD route or relationships route) and any kind of http methods as long as method return data. +You can restrict the fields returned by your API using the query string parameter called "fields". It is very useful for performance purposes because fields not returned are not resolved by the API. You can use the "fields" parameter on any kind of route (classical CRUD route or relationships route) and any kind of HTTP methods as long as the method returns data. .. note:: - Examples are not urlencoded for a better readability + Examples are not URL encoded for better readability -The syntax of a fields is like that :: +The syntax of the fields parameter is :: ?fields[]= @@ -22,20 +22,20 @@ Example: GET /persons?fields[person]=display_name HTTP/1.1 Accept: application/vnd.api+json -In this example person's display_name is the only field returned by the api. No relationships links are returned so the response is very fast because api doesn't have to compute relationships link and it is a very costly work. +In this example person's display_name is the only field returned by the API. No relationship links are returned so the response is very fast because the API doesn't have to do any expensive computation of relationship links. You can manage returned fields for the entire response even for included objects Example: -If you don't want to compute relationships links for included computers of a person you can do something like that +If you don't want to compute relationship links for included computers of a person you can do something like this .. sourcecode:: http GET /persons/1?include=computers&fields[computer]=serial HTTP/1.1 Accept: application/vnd.api+json -And of course you can combine both like that: +And of course you can combine both like this: Example: @@ -46,4 +46,4 @@ Example: .. warning:: - If you want to use both "fields" and "include" don't forget to specify the name of the relationship in fields; if you don't the include wont work. + If you want to use both "fields" and "include", don't forget to specify the name of the relationship in "fields"; if you don't, the include wont work.