From 8bc0966a2834cb85eeb04172d3fd64917993ada6 Mon Sep 17 00:00:00 2001 From: Christoph Kappestein Date: Mon, 18 Dec 2017 00:10:28 +0100 Subject: [PATCH] update request lifecycle doc --- doc/request_lifecycle.rst | 60 ++++++++++++++++++++------------------- 1 file changed, 31 insertions(+), 29 deletions(-) diff --git a/doc/request_lifecycle.rst b/doc/request_lifecycle.rst index d1bc9143..941efea6 100644 --- a/doc/request_lifecycle.rst +++ b/doc/request_lifecycle.rst @@ -2,32 +2,34 @@ Request lifecycle ================= -The following image illustrates the Fusio request lifecycle: - -.. image:: _static/backend_flow.png - -Route ------ - -If a request arrives Fusio looks at the routes table to find the fitting route. -The route has all information which request methods are allowed, how the request -and response schema is and what action to execute. If the route is protected -the request must contain an ``Authorization`` header with a fitting bearer token. -At this stage Fusio also checks the rate limits and rejects the request in case -the user has reached the request limit. - -Schema ------- - -The schema is a specification of the request or response data in the JSONSchema -format. It is not required to specify a schema for your endpoint but it is -recommended since the documentation is based on the schema. If the provided -data does not validate against the schema Fusio throws an error. - -Action ------- - -If the request arrives at the action the request payload is already validated -according to the schema. The action executes now the business logic of the -endpoint. A action can use connections in order to connect to a remote service -and execute a specific task. +To give you a first overview, every request which arrives at Fusio goes through +the following lifecycle: + +.. image:: _static/request_flow.png + +Fusio tries to assign the incoming request to a fitting route. The route +contains all schema information about the incoming request and outgoing +responses. Those schemas are also used at the documentation which is +automatically available. If a request schema was provided the incoming request +body gets validated after this schema. In case everything is ok the action +which is assigned to the route gets executed. + +An action represents the code which handles an incoming request and produces a +response. Each action can use connections to accomplish this task. A connection +uses a library which helps to work with a remote service. I.e. the SQL +connection uses the Doctrine DBAL library to work with a database (it returns +a ``Doctrine\DBAL\Connection`` instance). A connection always returns a fully +configured object so you never have to deal with any credentials in an action. +Besides that there are already many different actions available which you can +use i.e. to create an API based on a database table. + +With Fusio we want to remove as many layers as possible so that you can work +in your action directly with a specific library. Because of this Fusio has no +model or entity system like many other frameworks, instead we recommend to write +plain SQL in case you work with a relational database. We think that building API +endpoints based on models/entities limits the way how you would design a +response. You only need to describe the request and response in the JSON schema +format. This schema is then the contract of your API endpoint, how you produce +this response technically is secondary. Fusio provides the mentioned +connections, which help you to create complete customized responses based on +complicated SQL queries, message queue inserts or multiple remote HTTP calls.