search

encode / apistar

The Web API toolkit. 🛠
https://docs.apistar.com
BSD 3-Clause "New" or "Revised" License
5.57k stars 411 forks source link

APIStar as a cli-only API tool. #624

Closed tomchristie closed 5 years ago

tomchristie commented 5 years ago

This PR is working towards removing the server framework stuff from APIStar completely, in order to focus on cross-framework tooling for APIs, as discussed initially here: https://discuss.apistar.org/t/splitting-out-the-server/551/19

The initial set of CLI tools would be:

There would also be programmatic access to any of those functions, eg. Python API client that takes a schema on instantiation, and allows the user to then interact with the API.

The type system would also be a documented part of the library, along with API for generating HTML forms out of the types, and for marshalling between JSON Schema and APIStar types.

I haven't quite figured out what I want to do about the server stuff in APIStar (or not), but I'm not happy with it in it's current state, and Starlette does a far better job of pushing forward the fundamentals of an ASGI server.

I know this won't be a particularly popular direction, but I'm keen to focus APIStar on becoming a framework-agnostic tool, for generating and serving API documentation, using as an API client etc. rather than yet-another framework.

pikeas commented 5 years ago

This is very rough for projects built on APIStar. Do you plan to create a migration guide from APIStar to Starlette? Does Starlette have feature parity with APIStar?

tomchristie commented 5 years ago

So, Starlette takes advantage of ASGI properly, whereas for APIStar it's a bit bolted on. As a result there are a number of things that Starlette does (or soon will do) that aren't so obvious how to nicely build into APIStar, in particular:

It also does a much better job of clear, consistent design.

What it doesn't do, that APIStar does is:

I've not been convinced that APIStar's dependency injection is necessarily that great a solution to anything much, but even if I was, I'd rather see the projects properly scoped.

Here's some different paths we could go down:

  1. Do nothing. The existing apistar versions won't disappear so you just stay pinned to them.
  2. Have a fork of the project, under a different name. The only concrete changes here are that someone else would be doing the maintainance other than me, and that projects would need to change the import name to update.
  3. Forget about the DI layer, but make sure that there is suitable documentation and support for using apistar's type system and API docs together with starlette.
  4. I start a new project that combines apistar's types and API docs, with starlette for the base framework, and just adds in the DI layer and API docs. (ie. a continuation of apistar's server, but with a clear set of boundaries between the different projects.)
Bogdanp commented 5 years ago

@tomchristie I just noticed this after making https://github.com/encode/apistar/pull/625. Is there any chance of that landing and maybe being released as a final patch to the 0.5.x series? It's a fairly critical bug, imo. I can live with installing from my fork, but would prefer to install from PyPI (and not have to come up with a new namespace).

Re. options for current API Star users, I'd like to (shamelessly) propose my own framework, molten, as a sort of spiritual successor for those of us who don't need/want asyncio. Many of the concepts are similar (since APIStar was a huge inspiration!) so porting apps over should not be too difficult.

/end-shameless-plug

tomchristie commented 5 years ago

@Bogdanp Yup we can definitely do that. And great work on molten!

jeffbuttars commented 5 years ago

I've been looking forward to this transition!

@tomchristie I've been hoping for something along the path of the #3 option. The DI and docs features are what initially drew me to APIStar and I would love to see DI combined with Starlette, if it makes sense.

To me it appears option 1 is very viable, possibly as a WSGI only project? There seems to be clear preference among users who only want/need a WSGI based framework and enjoy having that with APIStar.