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.
Features
- 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)
Usage
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,
nullable=False,
server_default=func.now())
updated_at = Column(DateTime,
nullable=False,
server_default=func.now(),
onupdate=func.now())
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'
db.init_app(app)
api = Api(app)
with app.app_context():
db.create_all()
api.add_resource(CatListResource, '/cats')
api.add_resource(CatResource, '/cats/<int:instance_id>')
Query Engine
Filtering
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
.
Operators
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 |
Ordering
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.
Examples
/cats?$order_by=name
/cats?$order_by=pattern,-updated_at
Field selection
Use the $fields
query parameter to select a subset of fields. Fields are comma (,) separated.
Examples
/cats?$fields=id
/cats?$fields=id,name
Pagination
Use the $page
and $page_size
query parameters to paginate. $page_size
is not required and is 100 by default.
Examples
/cats?$page=2
/cats?$page=2&$page_size=10
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for restful_ben-0.4.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d3600a32d680acb28d1433caac93eeb0e9cb34b8169c737b8aac70f436af98cc |
|
MD5 | 323ef3fd9c68901c68d86dc55694f101 |
|
BLAKE2b-256 | 611f10bcec919bf8858bbe2c23dfd39bd28406a282ce4bced0563b33c0f22cd4 |