diff --git a/docs/cookbook.rst b/docs/cookbook.rst index 2e23683..ba1c04f 100644 --- a/docs/cookbook.rst +++ b/docs/cookbook.rst @@ -1,16 +1,16 @@ -Firetail Cookbook +FireTail Cookbook ================== This section aims to be a cookbook of possible solutions for specific -use cases of Firetail. +use cases of FireTail. Wildcard path parameters ------------------------ -Path parameters cannot contain slashes by default, but sometimes it's useful -to have a path parameter which takes the full remainder of the HTTP path -including slashes, e.g. to allow parsing "my/deep/path" from -"/pages/my/deep/path". Firetail supports parsing such path remainders +By default, path parameters cannot contain slashes, but sometimes it's useful +to have a path parameter that takes the full remainder of the HTTP path +including slashes, for example, to allow parsing "my/deep/path" from +"/pages/my/deep/path". FireTail supports parsing such path remainders by using ``format: path``: .. code-block:: yaml @@ -31,16 +31,16 @@ by using ``format: path``: Custom type format ------------------ -It is possible to define custom type formats that are going to be used -by the Firetail payload validation on request parameters and response +It is possible to define custom type formats that will be used +by the FireTail payload validation on request parameters and response payloads of your API. -Let's say your API deals with Products and you want to define a field +For example, if your API deals with Products and you want to define a field `price_label` that has a "money" format value. You can create a format checker function and register that to be used to validate values of the "money" format. -Example of a possible schema of Product having an attribute with +Below is an example of a possible schema of Product having an attribute with the "money" format that would be defined in your OpenAPI specification: .. code-block:: yaml @@ -67,15 +67,15 @@ Then we create a format checker function for that type of value: return True return MONEY_RE.match(val) -The format checker function is expected to return `True` when the -value matches the expected format and return `False` when it -doesn't. Also is important to verify if the type of the value you are -trying to validate is compatible with the format. In our example we +The format checker function returns `True` when the +value matches the expected format and returns `False` when it +doesn't. Also, it is important to verify if the type of the value you are +trying to validate is compatible with the format. In our example, we check if the `val` is of type "string" before performing any further checking. -The final step to make it work is registering our `is_money` function -to the format "money" in json_schema library. For that, we can use the +The final step is registering our `is_money` function +to the format "money" in the json_schema library. For that, we can use the draft4 format checker decorator. .. code-block:: python @@ -87,7 +87,7 @@ draft4 format checker decorator. ... This is all you need to have validation for that format in your -Firetail application. Keep in mind that the format checkers should be +FireTail application. Keep in mind that the format checkers should be defined and registered before you run your application server. A full example can be found at https://gist.github.com/rafaelcaricio/6e67286a522f747405a7299e6843cd93 @@ -96,7 +96,7 @@ https://gist.github.com/rafaelcaricio/6e67286a522f747405a7299e6843cd93 CORS Support ------------ -CORS_ (Cross-origin resource sharing) is not built into Firetail, but you can use the `flask-cors`_ library +CORS_ (Cross-origin resource sharing) is not built into FireTail, but you can use the `flask-cors`_ library to set CORS headers: .. code-block:: python @@ -120,9 +120,9 @@ to set CORS headers: Logging ------------ -You can customize logging accessing the `_flask-logger` directly -or configuring the logger via dictConfig. -Remember that you should configure logging for your project as soon +You can customize logging by accessing the `_flask-logger` directly +or configuring the logger using dictConfig. +Remember to configure logging for your project as soon as possible when the program starts or you'll get the default configuration. .. code-block:: python diff --git a/docs/exceptions.rst b/docs/exceptions.rst index 2fd3fb5..998136c 100644 --- a/docs/exceptions.rst +++ b/docs/exceptions.rst @@ -2,18 +2,18 @@ Exception Handling ================== Rendering Exceptions through the Flask Handler ---------------------------------------------- -Flask by default contains an exception handler, which firetail's app can proxy -to with the ``add_error_handler`` method. You can hook either on status codes +By default, Flask contains an exception handler, which FireTail's app can proxy +to with the ``add_error_handler`` method. You can either hook on status codes or on a specific exception type. -Firetail is moving from returning flask responses on errors to throwing exceptions +FireTail is moving from returning flask responses on errors to throwing exceptions that are a subclass of ``firetail.problem``. So far exceptions thrown in the OAuth decorator have been converted. Flask Error Handler Example --------------------------- -The goal here is to make the api returning the 404 status code +The goal here is to make the API returning the 404 status code when there is a NotFoundException (instead of 500) .. code-block:: python @@ -24,7 +24,7 @@ when there is a NotFoundException (instead of 500) assert response.status_code == 404 -Firstly, it's possible to declare what Exception must be handled +Firstly, it's possible to declare what Exception must be handled: .. code-block:: python @@ -88,7 +88,7 @@ and we know the API will return 404 status code. Default Exception Handling -------------------------- -By default firetail exceptions are JSON serialized according to +By default, FireTail exceptions are JSON serialized according to `Problem Details for HTTP APIs`_ Application can return errors using ``firetail.problem`` or exceptions that inherit from both @@ -106,8 +106,8 @@ exception Examples of Custom Rendering Exceptions --------------------------------------- -To custom render an exception when you boot your firetail application you can hook into a custom -exception and render it in some sort of custom format. For example +To custom render an exception when you boot your FireTail application you can hook into a custom +exception and render it in some sort of custom format. For example: .. code-block:: python @@ -124,23 +124,24 @@ exception and render it in some sort of custom format. For example Custom Exceptions ----------------- -There are several exception types in firetail that contain extra information to help you render appropriate +There are several exception types in FireTail that contain extra information to help you render appropriate messages to your user beyond the default description and status code: OAuthProblem ^^^^^^^^^^^^ -This exception is thrown when there is some sort of validation issue with the Authorisation Header +This exception is thrown when there is some sort of validation issue with the Authorisation Header. OAuthResponseProblem ^^^^^^^^^^^^^^^^^^^^ This exception is thrown when there is a validation issue from your OAuth 2 Server. It contains a -``token_response`` property which contains the full http response from the OAuth 2 Server +``token_response`` property which contains the full http response from the OAuth 2 Server. OAuthScopeProblem ^^^^^^^^^^^^^^^^^ This scope indicates the OAuth 2 Server did not generate a token with all the scopes required. This -contains 3 properties -- ``required_scopes`` - The scopes that were required for this endpoint -- ``token_scopes`` - The scopes that were granted for this endpoint +contains 3 properties: + +- ``required_scopes`` - The scopes that were required for this endpoint. +- ``token_scopes`` - The scopes that were granted for this endpoint. diff --git a/docs/index.rst b/docs/index.rst index e4928e9..090b84f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,22 +3,22 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to Firetail's documentation! +Welcome to FireTail's documentation! ===================================== -Firetail is a framework on top of Flask_ that automagically handles +FireTail is a framework on top of Flask_ that automagically handles HTTP requests defined using `OpenAPI`_ (formerly known as Swagger), supporting both `v2.0`_ and `v3.0`_ of the specification. -Firetail allows you to write these specifications, then maps the +FireTail allows you to write these specifications, then maps the endpoints to your Python functions. This is what makes it unique from other tools that generate the specification based on your Python code. You are free to describe your REST API with as much detail as -you want and then Firetail guarantees that it will work as -you specified. We built Firetail this way in order to: +you want and then FireTail guarantees that it will work as +you specified. We built FireTail this way in order to: -- Simplify the development process -- Reduce misinterpretation about what an API is going to look like +- Simplify the development process. +- Reduce misinterpretation about what an API is going to look like. Contents: diff --git a/docs/request.rst b/docs/request.rst index ceaa01a..461bbf5 100644 --- a/docs/request.rst +++ b/docs/request.rst @@ -1,6 +1,6 @@ Request Handling ================ -Firetail validates incoming requests for conformance with the schemas +FireTail validates incoming requests for conformance with the schemas described in swagger specification. Request parameters will be provided to the handler functions as keyword @@ -13,12 +13,12 @@ Request Validation Both the request body and parameters are validated against the specification, using `jsonschema`_. -If the request doesn't match the specification firetail will return a 400 +If the request doesn't match the specification FireTail will return a 400 error. Automatic Parameter Handling ---------------------------- -Firetail automatically maps the parameters defined in your endpoint +FireTail automatically maps the parameters defined in your endpoint specification to arguments of your Python views as named parameters and with value casting whenever possible. All you need to do is define the endpoint's parameters with matching names with your views arguments. @@ -48,11 +48,11 @@ And the view function: # do something return 'You send the message: {}'.format(message), 200 -In this example Firetail will automatically identify that your view +In this example FireTail will automatically identify that your view function expects an argument named `message` and will assign the value of the endpoint parameter `message` to your view function. -Firetail will also use default values if they are provided. +FireTail will also use default values if they are provided. If you want to use a parameter name that collides with a Python built-in, you can enable the `pythonic_params` option: @@ -62,7 +62,7 @@ you can enable the `pythonic_params` option: app = firetail.FlaskApp(__name__) app.add_api('api.yaml', ..., pythonic_params=True) -With this option enabled, Firetail firstly converts *CamelCase* names +With this option enabled, FireTail firstly converts *CamelCase* names to *snake_case*. Secondly it looks to see if the name matches a known built-in and if it does it appends an underscore to the name. @@ -117,7 +117,7 @@ And the view function: Type casting ^^^^^^^^^^^^ -Whenever possible Firetail will try to parse your argument values and +Whenever possible FireTail will try to parse your argument values and do type casting to related Python natives values. The current available type castings are: @@ -146,13 +146,13 @@ available type castings are: In the `OpenAPI 2.0 Specification`_ if you use the ``array`` type, you can define the ``collectionFormat`` to set the deserialization behavior. -Firetail currently supports "pipes" and "csv" as collection formats. +FireTail currently supports "pipes" and "csv" as collection formats. The default format is "csv". -Firetail is opinionated about how the URI is parsed for ``array`` types. +FireTail is opinionated about how the URI is parsed for ``array`` types. The default behavior for query parameters that have been defined multiple -times is to join them all together. For example, if you provide a URI with -the the query string ``?letters=a,b,c&letters=d,e,f``, firetail will set +times is to join them all together. For example, if you provide a URI with +the query string ``?letters=a,b,c&letters=d,e,f``, firetail will set ``letters = ['a', 'b', 'c', 'd', 'e', 'f']``. You can override this behavior by specifying the URI parser in the app or @@ -203,7 +203,7 @@ There are a handful of URI parsers included with connection. Parameter validation ^^^^^^^^^^^^^^^^^^^^ -Firetail can apply strict parameter validation for query and form data +FireTail can apply strict parameter validation for query and form data parameters. When this is enabled, requests that include parameters not defined in the swagger spec return a 400 error. You can enable it when adding the API to your application: @@ -218,7 +218,7 @@ Nullable parameters Sometimes your API should explicitly accept `nullable parameters`_. However OpenAPI specification currently does `not support`_ officially a way to serve -this use case, Firetail adds the `x-nullable` vendor extension to parameter +this use case, FireTail adds the `x-nullable` vendor extension to parameter definitions. Its usage would be: .. code-block:: yaml @@ -231,7 +231,7 @@ definitions. Its usage would be: x-nullable: true required: true -It is supported by Firetail in all parameter types: `body`, `query`, +It is supported by FireTail in all parameter types: `body`, `query`, `formData`, and `path`. Nullable values are the strings `null` and `None`. .. warning:: Be careful on nullable parameters for sensitive data where the diff --git a/docs/response.rst b/docs/response.rst index 8a0ba39..c1b556b 100644 --- a/docs/response.rst +++ b/docs/response.rst @@ -5,19 +5,19 @@ Response Serialization ---------------------- If the endpoint returns a `Response` object this response will be used as is. -Otherwise, and by default and if the specification defines that an endpoint -produces only JSON, firetail will automatically serialize the return value -for you and set the right content type in the HTTP header. +Otherwise, by default and if the specification defines that an endpoint +produces only JSON, FireTail automatically serializes the return value +for you and sets the right content type in the HTTP header. -If the endpoint produces a single non-JSON mimetype then Firetail will -automatically set the right content type in the HTTP header. +If the endpoint produces a single non-JSON mimetype then FireTail +automatically sets the right content type in the HTTP header. Customizing JSON encoder ^^^^^^^^^^^^^^^^^^^^^^^^ -Firetail allows you to customize the `JSONEncoder` class in the Flask app -instance `json_encoder` (`firetail.App:app`). If you wanna reuse the -Firetail's date-time serialization, inherit your custom encoder from +FireTail allows you to customize the `JSONEncoder` class in the Flask app +instance `json_encoder` (`firetail.App:app`). If you want to reuse the +FireTail's date-time serialization, inherit your custom encoder from `firetail.apps.flask_app.FlaskJSONProvider`. For more information on the `JSONEncoder`, see the `Flask documentation`_. @@ -30,7 +30,9 @@ There are two ways of returning a specific status code. One way is to return a `Response` object that will be used unchanged. -The other is returning it as a second return value in the response. For example +The other is returning it as a second return value in the response. + +For example: .. code-block:: python @@ -44,9 +46,9 @@ There are two ways to return headers from your endpoints. One way is to return a `Response` object that will be used unchanged. The other is returning a dict with the header values as the third return value -in the response: +in the response. -For example +For example: .. code-block:: python @@ -56,7 +58,7 @@ For example Response Validation ------------------- -While, by default Firetail doesn't validate the responses it's possible to +By default FireTail doesn't validate the responses it's possible to do so by opting in when adding the API: .. code-block:: python @@ -67,7 +69,7 @@ do so by opting in when adding the API: app.add_api('my_api.yaml', validate_responses=True) app.run(port=8080) -This will validate all the responses using `jsonschema` and is specially useful +This validates all the responses using `jsonschema` and is specially useful during development. @@ -89,7 +91,7 @@ the validation, you can override the default class with: Error Handling -------------- -By default firetail error messages are JSON serialized according to +By default FireTail error messages are JSON serialized according to `Problem Details for HTTP APIs`_ Application can return errors using ``firetail.problem``.