This project showcases my vision on how the RESTful API server should be implemented.

The goals that were achived in this example:

• RESTful API server should be self-documented using Swagger specifications, so interactive documentation UI is in place;
• Authentication is handled with OAuth2 and using Resource Owner Password Credentials Grant (Password Flow) for first-party clients makes it usable not only for third-party "external" apps;
• Permissions are handled (and automaticaly documented);
• PATCH method can be handled accordingly to RFC 6902.

I had to patch Flask-RESTplus (see flask_restplus_patched folder), so it can handle Marshmallow schemas and Webargs arguments.

This is still work-in-progress project, but it already has some value, so I publish it. Here is how it looks at this point of time:

• Python 2.7, 3.3+ / pypy2 (2.5.0)
• flask-restplus (flask, flask-restful)
• sqlalchemy (+ flask-sqlalchemy) - Database ORM.
• sqlalchemy-utils - for nice custom fields (e.g., PasswordField).
• alembic (+ flask-alembic) - for DB migrations.
• marshmallow (+ marshmallow-sqlalchemy, flask-marshmallow) - for schema definitions. (supported by the patched Flask-RESTplus)
• webargs - for parameters (input arguments). (supported by the patched Flask-RESTplus)
• apispec - for marshmallow and webargs introspection. (integrated into the patched Flask-RESTplus)
• oauthlib (+ flask-oauthlib) - for authentication.
• flask-login - for current_user integration only.
• bcrypt - for password hashing (used as a backend by sqlalchemy-utils.PasswordField).
• permission - for authorization.
• Swagger-UI - for interactive RESTful API documentation.

I use pyinvoke with custom tasks to maintain easy and nice command-line interface. Thus, it is required to have invoke Python package installed, and optionally you may want to install colorlog, so your life become colorful.

• flask-restplus is patched to handle marshmallow schemas and webargs input parameters (GH #9), and to be able to implement and document PATCH method as it is described in RFC 6902 (GH #11)
• swagger-ui (the bundle is included in this repo) just includes several pull-requests: JSON Editor (PR #1589), and Resource Owner Password Credentials Grant OAuth2 (Password Flow) (PR #1574)

It is very easy to start exploring the example using Docker:

$ docker run -it --rm --publish 5000:5000 frolvlad/flask-restplus-server-example

$ git clone https://github.com/frol/flask-restplus-server-example.git

It is recommended to use virtualenv or Anaconda/Miniconda to manage Python dependencies. Please, learn details yourself.

You will need invoke package to work with everything related to this project.

$ pip install invoke colorlog

NOTE: All dependencies and database migrations will be automatically handled, so go ahead and turn the server ON! (Read more details on this in Tips section)

$ invoke app.run

Open online interactive API documentation: http://127.0.0.1:5000/api/v1/

Autogenerated swagger config is always available from http://127.0.0.1:5000/api/v1/swagger.json

example.db (SQLite) includes 2 users:

• Admin user root with password q
• Regular user user with password w

NOTE: Use On/Off switch in documentation to sign in.

Once you have invoke, you can learn all available commands related to this project from:

$ invoke --list

Learn more about each command with the following syntax:

$ invoke --help <task>

For example:

$ invoke --help app.run
Usage: inv[oke] [--core-opts] app.run [--options] [other tasks here ...]

Docstring:
  Run DDOTS RESTful API Server.

Options:
  -d, --[no-]development
  -h STRING, --host=STRING
  -i, --[no-]install-dependencies
  -p, --port
  -u, --[no-]upgrade-db

Use the following command to enter ipython shell (ipython must be installed):

$ invoke app.env.enter

app.run and app.env.enter tasks automatically prepare all dependencies (using pip install) and migrate database schema to the latest version.

Database schema migration is handled via app.db.* tasks group. The most common migration commands are app.db.upgrade (it is automatically run on app.run), and app.db.migrate (creates a new migration).

• "The big Picture" - short yet complete idea about how the modern apps should talk.
• "Please. Don't PATCH Like An Idiot."
• "Best Practices for Designing a Pragmatic RESTful API"
• "My take on RESTful authentication"