Package: hapic
hapic in a nutshellhapic is a framework-agnostic library for coding professionnal REST APIs.Philosophyhapic as been developed by algoo in the context of a large service oriented project. The lack of a tool allowing real auto-documentation of Rest API has decided us to develop hapic.target usage is not for "quick and dirty" stuff but for professionnal, maintainable, long-term targeted projects.The separation of concerns between REST APIs layer and business stuff layer is in the DNA of hapic.hapic isjustthe HTTP layer glue code over your business code.Direct benefits of using hapicWhen you decide to base your development on hapic, you'll get direct benefits:Ready-to-usesupports aiohttp, flask, pyramid and bottleready-to-use with your existing librarieseffortless mapping of exceptions to HTTP errorsserialisation based on marshmallow schemas or serpyco dataclassesFull API documentation readyyour codeISthe documentationswagger generated documentationembed the documentation in 1 line of codesupports python 3.5, 3.6 and 3.7Professionnal and maintanable source codeseparation of concerns between business logic and HTTP stuffvery fast when used in conjunction with both aiohttp and serpycoextensible framework for supporting other web framework and serialisation librariesLicencehapic is licenced under the MIT licence. You can use it in your projects, closed or open sourced.status, contributionshapic source code is ready for production. Some refactoring are identified and required for maintainability, but public APIs are stable so you can rely on hapic for your developments.hapic is under active development, based on different professional projects. we will answer your questions and accept merge requests if you find bugs or want to include features.hapic is automatically tested on python 3.5, 3.6 and 3.7TODO referencesTODOs in the code can include some#xxx- these are github issues references.InstallationFor better performances with yaml module, you can install following (debian instruction):sudo apt-get install libyaml-devlibyaml-devpackage can be removed after hapic install.From source codevirtualenv-p/usr/bin/python3venvsourcevenv/bin/activate
pythonsetup.pydevelopTo work with Marshmallow schemas, install necessary dependencies:pip install -e ".[marshmallow]"To work with Serpyco dataclasses, install necessary dependencies:pip install -e ".[serpyco]"To have full environment (for developpers):pip install -e ".[dev"]From pypiTo work with Marshmallow schemas, install necessary dependencies:pip install hapic[marshmallow]To work with Serpyco dataclasses, install necessary dependencies:pip install hapic[serpyco]Give it a tryshort Flask examplefromdatetimeimportdatetimeimportflaskimportmarshmallowimporthapicfromhapic.ext.flaskimportFlaskContextimportjsonhapic=hapic.Hapic()app=flask.Flask(__name__)classUriPathSchema(marshmallow.Schema):# schema describing the URI and allowed valuesname=marshmallow.fields.String(required=True)age=marshmallow.fields.Integer(required=False)classHelloResponseSchema(marshmallow.Schema):# schema of the API responsename=marshmallow.fields.String(required=True)now=marshmallow.fields.DateTime(required=False)greetings=marshmallow.fields.String(required=False)@app.route('/hello/<name>')# flask route. must always be before hapic decorators@hapic.with_api_doc()# the first hapic decorator. Register the method for auto-documentation@hapic.input_path(UriPathSchema())# validate the URI structure@hapic.output_body(HelloResponseSchema())# define output structuredefhello(name='<No name>',hapic_data=None):return{'name':name,'now':datetime.now(),'dummy':{'some':'dummy'}# will be ignored}classUriPathSchemaWithAge(marshmallow.Schema):# schema describing the URI and allowed valuesname=marshmallow.fields.String(required=True)age=marshmallow.fields.Integer(required=False)@app.route('/hello/<name>/age/<age>')@hapic.with_api_doc()@hapic.input_path(UriPathSchemaWithAge())@hapic.output_body(HelloResponseSchema())defhello2(name='<No name>',age=42,hapic_data=None):return{'name':name,'age':age,'greetings':'Hello{name}, it looks like you are{age}'.format(name=name,age=age),'now':datetime.now(),'dummy':{'some':'dummy'}# will be ignored}hapic.set_context(FlaskContext(app))print(json.dumps(hapic.generate_doc(title='API Doc',description='doc desc.')))# Generate the documentationapp.run('127.0.0.1',8080,debug=True)How to use it:Nominal cases:$curl"http://127.0.0.1:8080/hello/michel"# {"now": "2017-12-18T12:37:10.751623+00:00", "name": "michel"}$curl"http://127.0.0.1:8080/hello/michel/age/17"# {"name": "damien", "greetings": "Hello damien, it looks like you are 17", "now": "2017-12-18T12:41:58.229679+00:00"}Error case (returns a 400):$curl"http://127.0.0.1:8080/hello/michel/age/mistaken"# {"details": {"age": ["Not a valid integer."]}, "message": "Validation error of input data"}A complete user APIIn theexample/usermanagementdirectory you can find a complete example of an API allowing to manage users.Features are:get list of all usersget detail of a given usercreate a userdelete a userIn order to test it :Install the required dependencies:pipinstallbottleflaskpyramid`Run the instance you wan to test (one of the three following lines):pythonexample/usermanagement/serve_bottle.py
pythonexample/usermanagement/serve_flask.py
pythonexample/usermanagement/serve_pyramid.pyFeatures shown :auto-generation of the documentationmanaging parameters in the uri pathmanaging input schemasmanaging output schemamanagement of error cases (404, 500, etc)nice exception handlingautomatic dict/object serialization