Carp-Api is an extension on top of flask micro-framework, it allows to build endpoints and sort outs exception handling. Allowing developers to just start coding restful-api and not be concerned by standard and mundane fuff.
What is CarpApi
Project is extension of Flask. Main goal is to simplify creation of restful api's. On high level carp-api is just standard flask app with a few additional features on top of it:
- endpoints are grouped into namespaces and namespaces use versioning (ie. we can have /1.0/user/create/ and /1.1/user/create/)
- endpoints are automatically propagated to every version that we have
- endpoints can override any existing endpoint from given version up
- input/output normalisation is provided by python-schema that will allow normalisation, validation and error handling
- support of open-api standard generation based on defined endpoints (TODO)
- error handling is configured out-of-box (TODO)
- user session and loggers are initially configured and easy to de-stub
It's answer to CRUD principle, carp-api helps you create any api that creates, amends, removes or picks resources (alternatively craft, alter, recover and pillage)
`pip install carp-api`
Or from source code:
`pip install -e firstname.lastname@example.org:Drachenfels/carp-api.git#egg=carp_api`
You are ready to roll!
Note about mandatory variables
Framework wraps around a standard Flask application and documentation for Flask
can be consulted. The main variable FLASK_APP is already preconfigured and set
carp_api.server_factory.server_factory:create_app. For most cases it's
good enough and server_factory allows to override any and all components it
uses to build an application. Another variable is SIMPLE_SETTINGS that defaults
carp_api.settings.base and should be replaced with project specific
settings file. Also all the variables typically exposed by Flask can be
overriden via settings module.
After successful installation new command will be available in shell
carp_api. This is a wrapper around flask with additional checks and defaults
set. For example standard flask would be
flask run vs
carp_api run or
flask routes is replaced with
Open base api in a browser by typing:
On default 3 endpoints are present /ping, /favicon.ico and / that returns list of all available endpoints.
Adding more endpoints
Assuming for versions 1.0 we want to add capaibilities to create a user, get list of all users and details about specific user, it would look like as follows.
In version 1.1 we want to add addresses that can be created for given user, altered and removed from user, while obtaining user details should return additional information. Also address deletion is considered dangerous and we do not want it to propagate to any future version.
In version 1.2 we want to add tags creation and deletion.
End effect all available urls will be as follows:
/1.0/user/ (POST) - creates a new user /1.0/user/ (GET) - get list of users /1.0/user/uid/<uid>/ (GET) - get specific user /1.1/user/ (POST) - creates a new user /1.1/user/ (GET) - get list of users /1.1/user/uid/<uid>/ (GET) - get specific user with address /1.1/user/uid/<uid>/address/ (POST) - create address for specific user /1.1/user/uid/<uid>/address/uid/<uid>/ (PUT) - alter existing address /1.1/user/uid/<uid>/address/<uid>/ (DELETE) - remove address /1.2/tag/ (POST) - create a tag /1.2/tag/ (GET) - get a tag /1.2/user/ (POST) - creates a new user /1.2/user/ (GET) - get list of users /1.2/user/uid/<uid>/ (GET) - get specific user with address /1.2/user/uid/<uid>/address/ (POST) - create address for specific user /1.2/user/uid/<uid>/address/uid/<uid>/ (PUT) - alter existing address
First inside of your project (let's call it
my_api) create file
it should contain following code:
from carp_api.routing import router from my_api import endpoints # version can be either, tuple, string or float number router.enable('1.0', 'user', endpoints=[ endpoints.CreateUser, endpoints.GetListOfUsers, ]) # we can keep enabling as many times as we like in non specific order # also version if provided as tuple may be build using strings or digits router.enable((1, '0'), 'user', endpoints=[ endpoints.GetUserByPk, ]) # this will override GetUserByPk from previous version router.enable('1.1', 'user', endpoints=[ endpoints.GetUserWithAddressByPk, ]) # namespace user/address will have no effect on url building router.enable('1.1', 'user/address', endpoints=[ endpoints.CreateUserAddress, endpoints.ChangeUserAddress, endpoints.DeleteUserAddress, ]) # enable version 1.2 that will have some additional functionality in form of # tags router.enable('1.2', 'tag', endpoints=[ endpoints.CreateTag, endpoints.GetListOfTags, ])
Then in a file
from carp_api.endpoint import BaseEndpoint class CreateUser(BaseEndpoint): url = '/' methods = ['POST'] class GetListOfUsers(BaseEndpoint): url = '/' class GetUserByPk(BaseEndpoint): url = '/uid/<id>' # add custom name to the endpoint to make easier override with another # class name = 'GetUserByPk' class CreateUserAddress(BaseEndpoint): url = '/' methods = ['POST'] @classmethod def get_final_url(cls, version, namespace, host=None): # method will override default url building return '/user/uid/<id>/address/' class ChangeUserAddress(BaseEndpoint): url = '/' methods = ['PUT'] @classmethod def get_final_url(cls, version, namespace, host=None): # method will override default url building return '/user/uid/<id>/address/uid/<id>/' class DeleteUserAddress(BaseEndpoint): url = '/' methods = ['DELETE'] # we do not want endpoint to go into future versions propagate = False class GetUserWithAddressByPk(GetUserByPk): url = '/uid/<id>/' class CreateTag(BaseEndpoint): url = '/' methods = ['POST'] class GetListOfTags(BaseEndpoint): url = '/'
Finally we will need to create project specific settings
that will keep following code:
from carp_api.settings.base import * # NOQA CARP_API_ROUTING = 'my_api.routing'
Now we can run our project with command:
SIMPLE_SETTINGS=my_api.settings carp_api run
And done, after we launch project it should have all endpoints resolved and ready to go.
Sample project ready to clone
Git clone Carp-Api Sample Project in order to have local project serving responses.
Planned features for sample project involve:
- pytest testing endpoints
- docker containers
- google app engine ready to use
- all main features of endpoint creation present
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size carp_api-0.1.1-py3-none-any.whl (40.8 kB)||File type Wheel||Python version py3||Upload date||Hashes View hashes|
|Filename, size carp_api-0.1.1.tar.gz (35.7 kB)||File type Source||Python version None||Upload date||Hashes View hashes|