airflow-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From danielvazgaspar@gmail.com <danielvazgas...@gmail.com>
Subject Re: FAB - New REST API in the works
Date Mon, 08 Apr 2019 09:03:03 GMT

Ok, so now ModelRestApi generates automatic OpenAPI specs from the CRUD endpoint, and made
the spec accessible on /api/<version>/_openapi. This endpoint is protected, but will
allow browser session cookies also (besides JWT).

BaseApi generates spec from YAML method docs. And offers 400-500 already bundled spec responses
for easy referencing ($ref: ) and Rison jsonschema integration and self registering on /components/parameters

I'm not bundling a swagger-ui also. Maybe this could be useful for dev.
 

On 2019/04/04 14:28:20, Ash Berlin-Taylor <ash@apache.org> wrote: 
> https://github.com/zalando/connexion was the other module we had started looking at in
Airflow to get OpenAPI for our API.
> 
> I think exposing the OpenAPI spec on an endpoint would be good too. The spec should be
"global" (at least tied to an API version) as all the tooling would expect a single endpoint/file
to query to build client libs - so `/api/v1/_openapi` for instance, and that would contain
info about all the endpoints in the v1 API. I don't understand your point about RBAC - accessing
the spec won't perform any actions so there aren't any permission concerns are there?
> 
> -ash
> 
> > On 4 Apr 2019, at 13:44, danielvazgaspar@gmail.com wrote:
> > 
> > 
> > On ModelResApi class, auto generated endpoints for CRUD rison args could be optional
but I would not go that way, some thoughts about this:
> > 
> > - ModelRestApi offers complex options for selecting columns, metadata keys, filters,
pagination, ordering. These options are naturally a nested data structure, and enabling this
kind of structure would force me to invent a specific key/value custom specification. I would
say that Rison is a standard way of solving this.
> > - Since Rison dumps and loads to JSON, I'm using JSON schema validation. This increases
the CRUD API resilience to malicious or unintentional faulty args.
> > - Rison solves out of the box, type arg conversion.
> > 
> > Note: You can use "normal" key/value args when developing your own API, extending
from BaseApi.    
> > 
> > Yes, good idea, OpenAPI spec is a very desirable feature, I was already looking
at: https://github.com/marshmallow-code/apispec. It seems very doable, even with dynamic schema
generation (I still have to try it). I have some doubts:
> > 
> > - Should we expose it on some endpoint, if yes, Should it be exposed resource based
/api/v1/<resource>/_openapi. Globally could raise issues regarding RBAC permissions.
> > 
> > 
> > On 2019/04/04 08:59:16, Ash Berlin-Taylor <ash@apache.org> wrote: 
> >> Some quick thoughts:
> >> 
> >> Rison: Is it optional? Can we (please?) still use query params too? Hand-crafting/what
the parameters look like in the URL is a total-non issue for me.
> >> 
> >> On that front it would be nice if `kwargs['rison']` was more general - to cope
with Rison or traditional query args in the same view based so something like `kwargs['get']`?
> >> 
> >> For example I instead of http://localhost:8080/api/v1/contact/1?q=(columns:!(name,address))'
I would prefer http://localhost:8080/api/v1/contact/1?columns=name,address  (or ?columns=name&columns=address)
> >> 
> >> And yes, having the API be self "documenting"/specifying with OpenAPI please!
This standard lets client libs be auto-generated based on the schema.
> >> 
> >> -ash
> >> 
> >> 
> >>> On 1 Apr 2019, at 18:49, danielvazgaspar@gmail.com wrote:
> >>> 
> >>> 
> >>> 
> >>> On 2019/04/01 17:14:28, Maxime Beauchemin <maximebeauchemin@gmail.com>
wrote: 
> >>>> Hey!
> >>>> 
> >>>> I wanted to point out that there's awesome work taking place in FAB
around
> >>>> a new REST API provided by the framework, and ways to extend it.
> >>>> 
> >>>> Daniel Gaspar (cced) is working on this currently, and looking for input
on
> >>>> design / implementation.
> >>>> 
> >>>> Check it out and chime in on the PR
> >>>> https://github.com/dpgaspar/Flask-AppBuilder/pull/929
> >>>> 
> >>>> I wanted to point out that a good place to start is by reading the
> >>>> `rest_api.rst` file in the PR (github collapses it in the PR interface
as
> >>>> it's large, and want to make sure people don't overlook that file)
> >>>> https://github.com/dpgaspar/Flask-AppBuilder/pull/929/files#diff-f0aaa98b108e6453b3a8b2526956b8beR1
> >>>> 
> >>>> Some key elements:
> >>>> * better and more flexible auth, using JWTs
> >>>> * Type awareness
> >>>> * a much better auto REST CRUD, with the ModelRestApi base class
> >>>> * a new way to define REST endpoints and a cohesive API, versioned as
in
> >>>> `/api/v1`
> >>>> * Rison integration
> >>>> * i18n
> >>>> 
> >>>> This should probably be the foundation to Airflow's REST API as it grows
> >>>> and this is a unique moment to influence the design of FAB's REST API.
> >>>> 
> >>>> Max
> >>>> 
> >>> Hi,
> >>> 
> >>> Feel free to leave comments on the PR or this thread. 
> >>> Once more you're input would be highly appreciated.
> >>> 
> >>> Docs are available on: https://flask-appbuilder.readthedocs.io/en/fab2/rest_api.html
> >>> (I'll be updating readthedocs for this branch)
> >>> 
> >>> Some design goals:
> >>> - Security
> >>> - Enable the possibility to develop dynamic CRUD react components on top
of the ModelRestApi class.
> >>> - Flexibility
> >>> - Coherent API
> >>> 
> >>> Thank you!
> >>> Daniel Gaspar
> >>> 
> >> 
> >> 
> 
> 

Mime
View raw message