encode / apistar Goto Github PK

Some things we could still consider:

• A component for accessing an individual element in the settings. (Q: How does this work given that we don't know what type it should be?)
• Validating settings(?)
• .get([keys]) to support lookups into the settings, without raising key errors when a section doesn't exist?

At some point I'd like to see us bring in a Django ORM backend that provides the functionality of the ORM and migrations framework. The developer productivity that Django brings there is pretty awesome, and I'd really like to see both this and SQLAlchemy be valid options.

Using any API from the browser obviously requires support for CORS. Django and Flask have several ways to integrate this, and I'd love to see that in this project. Not sure what the most effective way to enable this is.

In a small API I built just recently, I've got it hardcoded, but it would be great to identify the headers, and turn it on.

See TechEmpower/FrameworkBenchmarks#2633

as mentioned in #9

Currently considering:

• pipelines -> core
• main -> cli

In particular pipelines.ArgName reads weirdly in the docs.

Also considering renaming "views" to "handlers", given that they're more general purpose than a "view" onto some data.

We have these now but there's some stuff still missing...

• Support multiple template dirs.
• Support installed apps.
• Support multiple suffixes on Template component, and try each in turn.
• Raise ConfigurationError on unfound templates.
• Support a prefix on the Template component, so that folks can subclass to get a namespaced version.

Still some bits to do:

• URL Reversing
• Support include, and create sections in API schemas/docs.
• Figure out hostname binding (eg. search for example.com in our codebase)
• Path components
• Remove URLPathArg guard if URLPathArgs is used.

It should be possible to specify the host and port command for the run command. I would suggest --host and -h option for host and --port and -p option for port.

Remaining tasks from #62...

• Support components in annotations, eg. my_command(app: App)
• Return results should be echoed.
• Replace sys.exit usage with some handled exception.
• Replace click.echo with a console component.
• Refactor layout of tests.
• Documentation.
• Schema validation / error reporting.
• Proper implementation of Enum type
• Refactor to use new .native_type attribute in routing.
• Refactor and tidy up command routing.

Right now authentication and permissions have to be handled as custom components or inside the view handler. We'll want to provide some out of the box options here, such as JWT.

See #48

Use slack.in.
Could be just one channel, under "Encode" org?

Prefered option for ongoing conversations is probably Discourse... https://www.discourse.org/

Be completely clear about what types we do map, and eg.

• Support request components in command routing where possible (eg. query parameter)
• Raise errors in broken cases (eg. annotations that we don't undestand)
• Document what cases we support etc.
• Nice clean reprs on pipelines, refactoring if we can make the code more clear etc...

• Flake8
• isort
• MyPy

Right now we're hardwiring in JSON. We'll want to change that and add proper content negotiation.

Integrate whitenoise, and provide for collectstatic and static serving functionality.
Precursor to eg. #71.

Ensure that tests are always run against a fixed set of requirements.
Add a dev script that updates to the latest versions of everything.
Ensure that dev scripts such as scripts/setup deal correctly with updating when required.

Because, well, y'know.
It's kinda our baby.

• Tests running on Travis CI
• Badge

Add similar to django local dev server restart on source files changes

Once we've got the schemas fully in place we'd like to be able to run a mock API purely based on the function annotations, so that users can start up a mock API even before they've implemented any functionality.

We'd want to use randomised output that fits the given schema constraints, as well as validating any input, and returning those values accordingly.

eg.

schemas.py:

class KittenName(schema.String):
    max_length = 100


class KittenColor(schema.Enum):
    enum = [
        'black',
        'brown',
        'white',
        'grey',
        'tabby'
    ]

class Kitten(schema.Object):
    properties = {
        'name': KittenName,
        'color': KittenColor,
        'cuteness': schema.Number(
            minimum=0.0,
            maximum=10.0,
            multiple_of=0.1
        )
    }

views.py:

def list_favorite_kittens(color: KittenColor=None) -> List[Kitten]:
    """
    List your favorite kittens, optionally filtered by color.
    """
    pass

def add_favorite_kitten(name: KittenName) -> Kitten:
    """
    Add a kitten to your favorites list.
    """
    pass

We should be able to do this sort of thing...

$ apistar mock
mock api running on 127.0.0.1:5000

$ curl http://127.0.0.1:5000/kittens/fav/
[
    {
        "name": "congue",
        "color": "tabby",
        "cuteness": 5.9
    },
    {
        "name": "aenean",
        "color": "white",
        "cuteness": 9.3
    },
    {
        "name": "etiam",
        "color": "tabby",
        "cuteness": 8.8
    }
]

We mostly have pretty decent exception handling now, but still some bits to tie up:

• Document what we have.
• Schema exceptions are still incomplete for composite types.
• Provide customizable error handling to the developer, separating out 500 from managed exceptions.
• Replace our existing text tracebacks with a plain 500 and no extra info.

Implement Async support, using uvloop, and a gunicorn worker class.

command apistar new --template minimal returns:

~/devment/apistar » apistar new --template minimal                                                                                                                                                                 [apistar]sylwesterbrzeczkowski@Sylwesters-MacBook-Pro
Traceback (most recent call last):
  File "/Users/sylwesterbrzeczkowski/.virtualenvs/apistar/bin/apistar", line 7, in <module>
    from apistar.main import main
  File "/Users/sylwesterbrzeczkowski/.virtualenvs/apistar/lib/python3.6/site-packages/apistar/__init__.py", line 8, in <module>
    from apistar.app import App
  File "/Users/sylwesterbrzeczkowski/.virtualenvs/apistar/lib/python3.6/site-packages/apistar/app.py", line 5, in <module>
    from apistar import commands, routing
  File "/Users/sylwesterbrzeczkowski/.virtualenvs/apistar/lib/python3.6/site-packages/apistar/routing.py", line 9, in <module>
    from apistar import app, http, pipelines, schema, wsgi
  File "/Users/sylwesterbrzeczkowski/.virtualenvs/apistar/lib/python3.6/site-packages/apistar/http.py", line 10, in <module>
    import ujson as json
ModuleNotFoundError: No module named 'ujson'

Some initial work for this is now in place, but there's plenty more still to do:

• Add descriptions to fields and links.
• Support direct usage of QueryParam, RequestData.
• Include proper type information in the API Schemas.
• Include response schemas.
• Allow for API structure, using includes.
• Allow for eg _id -> id in function arguments, to work around python keyword-clashes.
• Allow for explicit naming in Route to override automatic function naming.
• Figure out encodings on links.
• API Name
• API Description
• API Base URL
• Document usage of client libraries.
• Figure out naming - APISchema vs schema module.
• Returning a schema from a view.

Similar to Django it would be interesting to have a CSRF mechanism for single-page applications running on client-side, eg. via a /csrf-token endpoint.

What are the thoughts on decorators? I am gradually working authentication/permissions into my API and was not sure which approach was planned for apistar.

Werkzeug can raise a RequestRedirect if eg. view is routed to /foo/, and a GET request is made to /foo (without the trailing slash).

We ought to be dealing with those in our exception handler function, and returning an appropriate response.

We oughta be able to route GraphQL endpoints to handlers.

We'd want a GraphQL query component that expresses the parameters of the query being made, and there's some considerations to play into our schema type system (eg. how we treat defaults and emptyness)

Load the os.environ in a validated format, using our type schemas to validate entries.

We'll be pulling in REST framework's existing interactive API docs.
It's gonna be ✨fabulous✨.

Validation of data fields

In a multistage environment the requirements and settings are typically different. Lets take a database as an example. You cold be running in-memory for the local environment but PSQL for the others (development, staging and production), although on different servers. This would require fine-grain adjustment of the datasources. In LoopBack this is dealt by setting the NODE_ENV to which ever environment you'd like and setting the naming convention of the files accordingly. With basis in the datasources, dataSources.json, it would look like following:

// dataSources.json
// This is the default file where NODE_ENV is null
{
    "db": {
        "name": "db",
        "connector": "memory"
    }
}

// dataSources.development.js
// This is the development settings where NODE_ENV=development
module.exports = 
{
    db:  {
        "name": "db",
        "connector": "postgresql"
        "host": "some-destination-for-dev-database.com"
        ...
    }
}

// dataSources.production.js
// This is the production settings where NODE_ENV=production
module.exports = 
{
    db:  {
        "name": "db",
        "connector": "postgresql"
        "host": "some-destination-for-production-db.com"        
        ...
    }
}

Its very likely that this could be done in a more elegant way..

This is a bit of a missing component ATM.
Parse the request body, raising 400 or 415 if required.
We'll want to automatically created TypedRequestData components for type arguments on POST requests.

Report test coverage in repo.

Use GitHub scripts style for development... https://github.com/github/scripts-to-rule-them-all

• /scripts/setup
• /scripts/update - Pushed to #36
• /scripts/test
• /scripts/lint
• /scripts/publish

Hey Tom, I was wondering about benchmarking the api performance on pull requests to see if they significantly affect the performance. Sort of like code coverage testing but against an API benchmark test instead. Just a thought!

I think that it would be great if internationalization could be provided out of the box without plugging in 3rd party solutions.

In the same way that Django REST framework provides an admin style interface on the API.
Would like to do something similar with API Star, in a way that we have a nice admin interface, but without being coupled to a particular backend.

For components that don't rely on the incoming request, we generally want to preload them into the state, so that we don't end up recreating them on every incoming request.

In particular this is true right now for our templates, where we're naively recreating the jinja environment on every incoming request. The interface for templates is already correct, but we need to be preloading them behind the scenes.

We have some of this in place at the moment, but we still need:

• Object
• Array
• Enum
• Documentation
• Defaults on schema types.
• Nullable

Plus a whole bunch of finessing around things like:

• Keyword defaults on handler functions.
• Support List in handler input types.
• Coerce primitive types to schema types? (eg. bool then handles "True"/"False" string literals, str then trims whitespace by default.)
• Returning aggregated validation errors for multiple parameters.
• Which typing annotations we support in views.
• Native formats such as datetime that have a string serialization.
• If we want to constrain the typing system against GraphQL, eg. no general "Map" type.

Requires either of #29, #9 first.

Client side support for live endpoints with content-diffs.
Support for notifications of updating live endpoints.

Rough benchmarking on trivial hello world, a simple point of comparison.

Requires #9.