New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

APIStar as a cli-only API tool. #624

Merged
merged 54 commits into from Sep 25, 2018

Conversation

Projects
None yet
4 participants
@tomchristie
Copy link
Member

tomchristie commented Sep 17, 2018

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:

  • apistar validate - Validate an OpenAPI or Swagger schema.
  • apistar doc - Generate API documentation, given an API schema.
  • apistar request - Make a client request to an API.
  • apistar mock - Serve a mock API.

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.

tomchristie added some commits Sep 6, 2018

@tomchristie tomchristie referenced this pull request Sep 17, 2018

Closed

[WIP] Add Open API schema generation. #6119

1 of 10 tasks complete
@pikeas

This comment has been minimized.

Copy link

pikeas commented Sep 17, 2018

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

This comment has been minimized.

Copy link
Member

tomchristie commented Sep 18, 2018

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:

  • Websockets.
  • Server Sent Events. (soon)
  • In-process background tasks. (soon)
  • HTTP/2 and server push. (soon)

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

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

  • Dependency Injection for handler arguments.
  • API documentation.

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.)

tomchristie added some commits Sep 19, 2018

@tomchristie tomchristie merged commit 2338552 into master Sep 25, 2018

2 checks passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
continuous-integration/travis-ci/push The Travis CI build passed
Details

@tomchristie tomchristie deleted the cli-only branch Sep 25, 2018

@tomchristie tomchristie referenced this pull request Sep 26, 2018

Closed

Need help #626

tomchristie added a commit to tomchristie/asgiref that referenced this pull request Sep 26, 2018

Drop API Star
Drop API Star, since from 0.6 onwards it's [descoped into a framework-agnostic suite of API tools](encode/apistar#624), rather than a complete server implementation. (Starlette has picked up the mantle for my own work on an ASGI framework implementation.)

andrewgodwin added a commit to django/asgiref that referenced this pull request Sep 27, 2018

Drop API Star (#67)
Drop API Star, since from 0.6 onwards it's [descoped into a framework-agnostic suite of API tools](encode/apistar#624), rather than a complete server implementation. (Starlette has picked up the mantle for my own work on an ASGI framework implementation.)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment