Skip to main content

A composable SQLAlchemy based RESTful API library.

Project description

RESTful Ben

Ben's had a nap, he's feeling RESTful and ready to go.

A libray to assist creating SQLAlchemy, Flask, and flask-restful based APIs.


  • RESTful resources
    • Generates POST, GET (individual and list), PUT, and DELETE endpoints based on a SQLAlchemy model and a Marshmallow schema.
    • Query engine
      • Field selection
      • Filtering
      • Sorting
      • Pagination
  • Authentication
    • Username and password based sessions
    • CSRF
    • Session endpoint - login (POST) and logout (DELETE)
  • Authorization
    • Basic role based authorization
    • Roles map to HTTP verbs (GET, POST, etc)


Basic API

Create a model

class Cat(BaseModel):
    __tablename__ = 'cats'

    id = Column(Integer, primary_key=True)
    name = Column(String, nullable=False)
    pattern = Column(String)
    age = Column(Integer)
    created_at = Column(DateTime,
    updated_at = Column(DateTime,

Create a Marshmallow schema to map a model to a JSON representation. This uses Marshmallow SQLAlchemy to generate the schema automatically.

class CatSchema(ModelSchema):
    class Meta:
        model = Cat

    id = field_for(Cat, 'id', dump_only=True)
    created_at = field_for(Cat, 'created_at', dump_only=True)
    updated_at = field_for(Cat, 'updated_at', dump_only=True)

cat_schema = CatSchema()
cats_schema = CatSchema(many=True)

Create a resource for single Cat access, eg /cats/:id

class CatResource(RetrieveUpdateDeleteResource):
    single_schema = cat_schema
    model = Cat
    session = db.session

Create a resource for listing Cats, eg /cats.

class CatListResource(QueryEngineMixin, CreateListResource):
    single_schema = cat_schema
    many_schema = cats_schema
    model = Cat
    session = db.session

Setup your flask app:

import flask
from flask_sqlalchemy import SQLAlchemy
from flask_restful import Api

from .routes import CatListResource, CatResource

db = SQLAlchemy()

app = flask.Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = 'some db'

api = Api(app)

with app.app_context():

    api.add_resource(CatListResource, '/cats')
    api.add_resource(CatResource, '/cats/<int:instance_id>')

Query Engine


To filter based on equality simple use the field name plus filter value for one or more fields, ex /cats?pattern=Tabby. Other operations are available by adding an operator at the end of the field name separated by two underscores, ex /cats?pattern__contains=Tabby.


Operator Description Notes / Example
eq Equals - default /cats?pattern=Tabby or /cats?pattern__eq=Tabby
ne Not Equals (!=) /cats?pattern__ne=Tabby
lt Less Than (<)
lte Less Than or Equal To (<=)
gt Greater Than (>)
gte Greater Than or Equal To (>=)
contains Contains
like Like
ilike Case Insensitive Like
notlike Not Like
notilike Case Insensitive Not Like
startswith Starts With
endswith Ends With
in In /cats?name__in=Ada&name__in=Leo
notin Not In /cats?name__notin=Ada&name__notin=Leo
is IS - Helper for null and true/false /cats?age__is=null or /users?active__is=true or /users?active__is=false
isnot IS NOT - Helper for null and true/false /cats?age__isnot=null


Use the $order_by query parameter to set ordering by one or more fields. Fields are separated by a comma (,) and are ascending by default. Add a minus to the beginning of the field to order by descending.




Field selection

Use the $fields query parameter to select a subset of fields. Fields are comma (,) separated.





Use the $page and $page_size query parameters to paginate. $page_size is not required and is 100 by default.




Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for restful-ben, version 0.4.2
Filename, size File type Python version Upload date Hashes
Filename, size restful_ben-0.4.2-py3-none-any.whl (11.2 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size restful-ben-0.4.2.tar.gz (12.1 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page