API development made easy: a smart Python 3 API framework

Overview

appkernel - API development made easy

alt build_status alt issues alt coverage GitHub license

What is Appkernel?

A super-easy to use API framework, enabling API creation from zero to production within minutes (no kidding: literally within minutes).

It provides data serialisation, transformation, validation, security, ORM, RPC and service mash functions out of the box (check out the roadmap for more details).

... and finally give a vote on awesome-python if you like the project, so it gets added to the list of RESTful python frameworks. Only 15 more votes are missing :)

Installation

    pip install appkernel

Crash Course

Let's build an awseome mini identity service:

class User(Model, MongoRepository):
    # define the resource schema as class meta data
    id = Property(str)
    name = Property(str, index=UniqueIndex)
    email = Property(str, validators=[Email], index=UniqueIndex)
    password = Property(str, converter=content_hasher(), omit=True)
    roles = Property(list, sub_type=str, default_value=['Login'])

    @classmethod
    def before_post(cls, *args, **kwargs):
        # this method is automatically called before persisting the instance
        # one can use after_post for hook after the persistence.
        user = kwargs.get('model')
        print(f'going to create the following user: {user}')



if __name__ == '__main__':
    # let's expose the user resource
    kernel = AppKernelEngine()
    kernel.register(User)

    # let's create and persist a sample user
    user = User(name='Test User', email='[email protected]', password='some pass')
    user.save()

    # and we are all set
    kernel.run()

That's all folks, our user service is ready to roll, the entity is saved, we can re-load the object from the database, or we can request its json schema for validation, or metadata to generate an SPA (Single Page Application). Of course validation and some more goodies are built-in as well :)

Retrieving our our User, using HTTP requests

GET request:

curl -i -X GET \
 'http://127.0.0.1:5000/users/'

And the result:

{
  "_items": [
    {
      "_type": "User",
      "email": "[email protected]",
      "id": "U0590e790-46cf-42a0-bdca-07b0694d08e2",
      "name": "Test User",
      "roles": [
        "Login"
      ]
    }
  ],
  "_links": {
    "self": {
      "href": "/users/"
    }
  }
}

Adding extra and secure methods using the @action decorator is easy as well:

@action(method='POST', require=[CurrentSubject(), Role('admin')])
def change_password(self, current_password, new_password):
    if not pbkdf2_sha256.verify(current_password, self.password):
        raise ServiceException(403, _('Current password is not correct'))
    else:
        self.password = new_password
        self.save()
    return _('Password changed')

The example above exposes the http://base_url/users/<user_id>/change_password endpoint and allows the user with admin role or the user with the current user_id to call it.

Create additional hooks, which are called before and after a HTTP method is executed, by simply adding a static method to the Model class following the convention: before_{http_method} and after_{http_method}:

Example:

@classmethod
def before_post(cls, *args, **kwargs):
    user = kwargs.get('model')
    print(f'going to create this user: {user}')

or inspect (and alter) the already persisted object:

@classmethod
def after_post(cls, *args, **kwargs):
    user = kwargs.get('model')
    print(f'this user was created: {user}')

We can also call other services using the built-in REST client proxy. In the snippet bellow we call the reservations endpoint on the Inventory service, by POST-ing a Reservation object.

    client = HttpClientServiceProxy('http://127.0.0.1:5000/')
    status_code, rsp_dict = client.reservations.post(Reservation(order_id=order.id, products=order.products))

Some features of the REST endpoint

  • GET /users/12345 - retrieve a User object by its database ID;
  • GET /users/?name=Jane&email=[email protected] - retrieve the User named Jane with e-mail address [email protected];
  • GET /users/?name=Jane&name=John&logic=OR - retrieve Jane or John;
  • GET /users/?roles=~Admin - retrieve all users which have the role Admin;
  • GET /users/?name=[Jane,John] - retrieve all user with the name Jane or John;
  • GET /users/?inserted=>2018-01-01&inserted=<2018-12-31 - return all users created in 2018;
  • GET /users/?page=1&page_size=5&sort_by=inserted&sort_order=DESC - return the first page of 5 elements;
  • GET /users/?query={"$or":[{"name": "Jane"}, {"name":"John"}]} - return users filtered with a native Mongo Query;
  • GET /users/meta - retrieve the metadata of the User class for constructing self-generating SPAs;
  • GET /users/schema - return the Json Schema of the User class used for validating objects;

Additionally the following HTTP methods are supported:

  • POST: create a new user (or updates existing one by replacing it) using a json payload or multipart form data
  • PATCH: add or updates some fields on the User object
  • PUT: replaces a User object

A few features of the built-in ORM function

Find one single user matching the query Property:

user = User.where(name=='Some username').find_one()

Return the first 5 users which have the role "Admin":

user_generator = User.where(User.roles % 'Admin').find(page=0, page_size=5)

Or use native Mongo Query:

user_generator = Project.find_by_query({'name': 'user name'})

Atomic updates:

# reserve 10 products with product code TRS abd size M
query = StockInventory.where((StockInventory.product.code == 'TRS') & (StockInventory.product.size == ProductSize.M))
for _ in range(10):
    ...
    query.update(available=StockInventory.available - 1, reserved=StockInventory.reserved + 1)

One could extend the AuditedMongoRepository mixin instead of the MongoRepository and we would end up with 3 extra fields:

  • inserted: the date-time of insertion;
  • updated: the date-time of the last update;
  • version: the number of versions stored for this document;

Some more extras baked into the Model

Generate the ID value automatically using a uuid generator and a prefix 'U':

id = Property(..., generator=uuid_generator('U'))

Add a Unique index to the User's name property:

name = Property(..., index=UniqueIndex)

Validate the e-mail property, using the NotEmpty and Email validators

email = Property(..., validators=[Email, NotEmpty])

Add schema validation to the database:

User.add_schema_validation(validation_action='error')

Hash the password and omit this attribute from the json representation:

password = Property(..., converter=content_hasher(rounds=10), omit=True)

Run the generators on the attributes and validate the object (usually not needed, since it is implicitly called by save and dumps methods):

user.finalise_and_validate()

Security is also part of the mix

The following snippet shows the declarative way of access control:

user_service = kernel.register(User, methods=['GET', 'PUT', 'POST', 'PATCH', 'DELETE'])
user_service.deny_all().require(Role('user'), methods='GET').require(Role('admin'),
                                                                         methods=['PUT', 'POST', 'PATCH', 'DELETE'])
  1. user_service.deny_all(): by default access to all methods is forbidden;
  2. require(Role('user'), methods='GET'): GET methods can be used by users having the Role: user (basic login role);
  3. require(Role('admin'), methods=['PUT', 'POST', 'PATCH', 'DELETE']): one needs the Role: admin in order to call other http methods;

I want to know the current status of the project

For more details feel free to check out the documentation

What are we building here?

The vision of the project is to provide you with a full-fledged microservice chassis, as defined by Chris Richardson to help creating beautiful APIs quikly and efficiently.

How does it helps you?

We've spent the time on analysing the stack, made the hard choices for you in terms of Database/ORM/Security/Rate Limiting and so on, so you don't have to. You can focus entirely on delivering business value from day one and being the rockstar of your project.

Currently supported (and fully tested) features:

  • REST endpoints over HTTP
  • Full range of CRUD operations
  • Customizable resource endpoints
  • Customizable, multiple item endpoints
  • Filtering and Sorting
  • Pagination
  • Data Validation
  • Extensible Data Validation
  • Default Values
  • Projections
  • Embedded Resource Serialization
  • Custom ID Fields
  • MongoDB Aggregation Framework
  • Powered by Flask

Contribute

Be part of the development: contribute to the project :)

Why did we built this?

  • We had the need to build a myriad of small services in our daily business, ranging from data-aggregation pipelines, to housekeeping services and other process automation services. These do share similar requirements and the underlying infrastructure needed to be rebuilt and tested over and over again. The question arose: what if we avoid spending valuable time on the boilerplate and focus only on the fun part?

  • Often time takes a substantial effort to make a valuable internal hack or proof of concept presentable to customers, until it reaches the maturity in terms reliability, fault tolerance and security. What if all these non-functional requirements would be taken care by an underlying platform?

  • There are several initiatives out there (Flask Admin, Flask Rest Extension and so), which do target parts of the problem, but they either need substantial effort to make them play nice together, either they feel complicated and uneasy to use. We wanted something simple and beautiful, which we love working with.

These were the major driving question, which lead to the development of App Kernel.

How does it works?

AppKernel is built around the concepts of Domain Driven Design. You can start the project by laying out the model. The first step is to define the validation and data generations rules. For making life easier, one can also set default values. Than one can extend several built-in classes in order to augment the model with extended functionality:

  • extending the Repository class (or its descendants) adds and ORM persistency capability to the model;
  • extending the Service class (or its descendants) add the capablity to expose the model over REST services;
You might also like...
Tracking development of the Class Schedule Siri Shortcut, an iOS program that checks the type of school day and tells you class scheduling.

Class Schedule Shortcut Tracking development of the Class Schedule Siri Shortcut, an iOS program that checks the type of school day and tells you clas

Structured, dependable legos for starknet development.

Structured, dependable legos for starknet development.

Traditionally, there is considerable friction for developers when setting up development environments

This self-led, half-day training will teach participants the patterns and best practices for working with GitHub Codespaces

World Happiness Report is a publication of the Sustainable Development Solutions Network

World-Happiness-Report We are going to visualise what are the factors and which

Gba-free-fonts - Free font resources for GBA game development
Gba-free-fonts - Free font resources for GBA game development

gba-free-fonts Free font resources for GBA game development This repo contains m

Simple and easy to use python API for the COVID registration booking system of the math department @ unipd (torre archimede)

Simple and easy to use python API for the COVID registration booking system of the math department @ unipd (torre archimede). This API creates an interface with the official browser, with more useful functionalities.

This repository provides a set of easy to understand and tested Python samples for using Acronis Cyber Platform API.

Base Acronis Cyber Platform API operations with Python !!! info Copyright © 2019-2021 Acronis International GmbH. This is distributed under MIT licens

Driving lessons made simpler. Custom scheduling API built with Python.
Driving lessons made simpler. Custom scheduling API built with Python.

NOTE This is a mirror of a GitLab repository. Dryvo Dryvo is a unique solution for the driving lessons industry. Our aim is to save the teacher’s time

A PG3D API Made with Python

PG3D Python API A Pixel Gun 3D Python API (Public Ver) Features Count: 29 How To Use? import api as pbn Examples pbn.isBanned(192819483) - True pbn.f

Comments
  • Logo Design

    Logo Design

    Hi. I am a graphic designer. I volunteer to design a logo for open source projects. I can design it for you to use it in the readme file. What dou you say?

    opened by Batarian711 4
  • print() is a function in Python 3

    print() is a function in Python 3

    flake8 testing of https://github.com/accelero-cloud/appkernel on Python 3.6.3

    $ flake8 . --count --select=E901,E999,F821,F822,F823 --show-source --statistics

    ./appkernel/compat.py:10:1: F822 undefined name 'unicode' in __all__
    __all__ = ('bytes', 'set', 'unicode', 'long', 'unichr', 'queue')
    ^
    ./appkernel/compat.py:10:1: F822 undefined name 'unichr' in __all__
    __all__ = ('bytes', 'set', 'unicode', 'long', 'unichr', 'queue')
    ^
    ./appkernel/engine.py:44:25: F821 undefined name 'iterable'
                return list(iterable)
                            ^
    ./appkernel/hacks/hacks.py:16:48: E999 SyntaxError: invalid syntax
            print "Creating table %s with fields %s" % (self.table_name, self.fields)
                                                   ^
    ./appkernel/hacks/ioc.py:137:22: E999 SyntaxError: invalid syntax
                print self.prefix, message
                         ^
    ./tutorials/metaprogramming/order_processing_b.py:43:43: E999 SyntaxError: invalid syntax
            print '>> Audit time: %r  %2.2f ms' % (method.__name__, (te - ts) * 1000)
                                              ^
    ./tutorials/metaprogramming/order_processing_c.py:42:39: E999 SyntaxError: invalid syntax
        print '>> Audit time: %r  %2.2f ms' % (wrapped_function.__name__, (te - ts) * 1000)
                                          ^
    4     E999 SyntaxError: invalid syntax
    1     F821 undefined name 'iterable'
    2     F822 undefined name 'unicode' in __all__
    7
    
    opened by cclauss 1
  • Config file for pyup.io

    Config file for pyup.io

    Hi there and thanks for using pyup.io!

    Since you are using a non-default config I've created one for you.

    There are a lot of things you can configure on top of that, so make sure to check out the docs to see what I can do for you.

    opened by pyup-bot 0
  • Initial Update

    Initial Update

    The bot created this issue to inform you that pyup.io has been set up on this repo. Once you have closed it, the bot will open pull requests for updates as soon as they are available.

    opened by pyup-bot 0
Releases(v1.2.4)
  • v1.2.4(Sep 15, 2018)

  • v1.2.0(Sep 14, 2018)

    • production ready gevent based WSGI server is initialised (if pip install gevent is issued prior to launching the service)
    • simplified service initialistion
    • unified and improved logging
    • additional documentation regarding installation and integration into own project
    Source code(tar.gz)
    Source code(zip)
  • v1.1.0(Sep 9, 2018)

    Changes

    • bugfixes on the validation framework
    • possible to expose services which do not inherit from the Model class
    • @link decorator renamed to @action
    • introduced @resource decorator for easy method exposure on plain classes
    • http rpc client
    • complete tutorial is added to the project
    • bulk inserts
    • atomic updates
    • extended Query methods (update_one, find_one_and_update, etc.)
    Source code(tar.gz)
    Source code(zip)
  • v1.0(Jul 8, 2018)

    Model

    • [x] validation on the data model using multiple custom validators
    • [x] json serialisation support
    • [x] json schema generator
    • [x] value generators
    • [x] value converters
    • [x] wire-format marshaller
    • [x] omitted fields

    ORM Feature

    • [x] basic CRUD (create/update/delete) operations
    • [x] easy to use active record style queries
    • [x] automatically generated prefixed database ID
    • [x] index management (unique index, text index, etc.) on the database
    • [x] database schema validation and schema management
    • [x] builtin converters for serialising or deserialising the model to and from various other formats
    • [x] audited fields (eg. automatically added created, updated, updated_by fields)
    • [x] document versioning
    • [x] Bulk Inserts

    REST Service Endpoints

    • [x] REST services (GET, PUT, POST, PATCH, DELETE)
    • [x] HATEOAS actions on model
    • [x] model metadata and json schema
    • [x] URL query interface
    • [x] Read-only by default
    • [x] role based account management (RBAC)
    • [x] basic authentication and JWT token support
    • [x] customised, machine readable error messages
    Source code(tar.gz)
    Source code(zip)
A platform for developers 👩‍💻 who wants to share their programs and projects.

Fest-Practice-2021 This project is excluded from Hacktoberfest 2021. Please use this as a testing repo/project. A platform for developers 👩‍💻 who wa

Mayank Choudhary 40 Nov 07, 2022
A curated collection of Amazing Python scripts from Basics to Advance with automation task scripts

📑 Introduction A curated collection of Amazing Python scripts from Basics to Advance with automation task scripts. This is your Personal space to fin

Amitesh kumar mishra 1 Jan 22, 2022
A self contained invitation management system for gatekeeping.

Invitease Description A self contained invitation management system for gatekeeping. Purpose Serves as a focal point for inviting guests to a venue pr

מעגן מיכאל 7 Jul 19, 2022
About Python's multithreading and GIL

About Python's multithreading and GIL

Souvik Ghosh 3 Mar 01, 2022
Fofa asset consolidation script

资产收集+C段整理二合一 基于fofa资产搜索引擎进行资产收集,快速检索目标条件下的IP,URL以及标题,适用于资产较多时对模糊资产的快速检索,新增C段整理功能,整理出

白泽Sec安全实验室 36 Dec 01, 2022
API to summarize input text

summaries API to summarize input text normal run $ docker-compose exec web python -m pytest disable warnings $ docker-compose exec web python -m pytes

Brad 1 Sep 08, 2021
全局指针统一处理嵌套与非嵌套NER

GlobalPointer 全局指针统一处理嵌套与非嵌套NER。 介绍 博客:https://kexue.fm/archives/8373 效果 人民日报NER 验证集F1 测试集F1 训练速度 预测速度 CRF 96.39% 95.46% 1x 1x GlobalPointer (w/o RoPE

苏剑林(Jianlin Su) 183 Jan 06, 2023
Make creating Excel XLSX files fun again

Poi: Make creating Excel XLSX files fun again. Poi helps you write Excel sheet in a declarative way, ensuring you have a better Excel writing experien

Ryan Wang 11 Apr 01, 2022
The best way to learn Python is by practicing examples. The repository contains examples of basic concepts of Python. You are advised to take the references from these examples and try them on your own.

90_Python_Exercises_and_Challenges The best way to learn Python is by practicing examples. This repository contains the examples on basic and advance

Milaan Parmar / Милан пармар / _米兰 帕尔马 205 Jan 06, 2023
Osu statistics right on your desktop, made with pyqt

Osu!Stat Osu statistics right on your desktop, made with Qt5 Credits Would like to thank these creators for their projects and contributions. ppy, osu

Aditya Gupta 21 Jul 13, 2022
JSEngine is a simple wrapper of Javascript engines.

JSEngine This is a simple wrapper of Javascript engines, it wraps the Javascript interpreter for Python use. There are two ways to call interpreters,

11 Dec 18, 2022
Tutorials on advanced python topics, and literate programming framework to write them.

Advanced course on Python3 This course covers several topics Python decorators The python object system / meta classes Also see my text on Python impo

Michael Moser 59 Dec 19, 2022
"Hacking" the (Telekom) Zyxel GPON SFP module (PMG3000-D20B)

"Hacking" the (Telekom) Zyxel GPON SFP module (PMG3000-D20B) The SFP can be sour

Matthias Riegler 52 Jan 03, 2023
Coursework project for DIP class. The goal is to use vision to guide the Dashgo robot through two traffic cones in bright color.

Coursework project for DIP class. The goal is to use vision to guide the Dashgo robot through two traffic cones in bright color.

Yueqian Liu 3 Oct 24, 2022
Simplest way to find Appointments in Bürgeramt Berlin, Not over engineered.

Simplest way to find Appointments in Bürgeramt Berlin, Not over engineered. Der einfachste Weg, Termine im Bürgeramt Berlin zu finden, ohne viel Schnickschnack.

Jannis 8 Nov 25, 2022
WhyNotWin11 - Detection Script to help identify why your PC isn't Windows 11 Release Ready

WhyNotWin11 - Detection Script to help identify why your PC isn't Windows 11 Release Ready

Robert C. Maehl 5.9k Dec 31, 2022
Run PD patches in NRT using Python

The files in this repository demonstrate how to use Pure Data (Pd) patches designed to run in Non-Real-Time mode to batch-process (synthesize, analyze, etc) sounds in series using Python.

Jose Henrique Padovani 3 Feb 08, 2022
The bidirectional mapping library for Python.

bidict The bidirectional mapping library for Python. Status bidict: has been used for many years by several teams at Google, Venmo, CERN, Bank of Amer

Joshua Bronson 1.2k Dec 31, 2022
A reference implementation for processing the content.log files found at opendata.dwd.de/weather

A reference implementation for processing the content.log files found at opendata.dwd.de/weather.

Deutscher Wetterdienst (DWD) 6 Nov 26, 2022
Python script for diving image data to train test and val

dataset-division-to-train-val-test-python python script for dividing image data to train test and val If you have an image dataset in the following st

Muhammad Zeeshan 1 Nov 14, 2022