Alpha API system
Introduction
The api system is completely based on Flask and compatible. You could use Flask inside Alpha system without any issue.
Launch
To start the api execute the api.py
file
python api.py
Note
set ALPHA_CONF
environment parameter is you want to set the environment.
Verify the deployment by navigating to your server address in your preferred browser:
127.0.0.1:<port>
How to use
Your could import it using simply from the utils:
from alphaz.utils.api import api
or from the core if you are using it
from core import core
api = core.api
api is the equivalent for app in Flask framework.
Configuration
The api is automatically configured from the api.jon
file.
Admin
You could specify ip in the admins parameter.
Routes
Basic
To specify an api route, juste use the route
flag:
from alphaz.utils.api import route, api, Parameter
@route("route_name")
def method_name():
return "hello"
Method automatically convert the output to the right format. Default format is json
Description
A description could be specified:
@route("route_name", description="This route say hello")
def method_name():
return "hello"
Category
The routes are organized by category
, by default the route category is defined by it file name, but it could be specified using the cat
parameter:
@route("route_name", category="politeness")
def method_name():
return "hello"
Parameters
Simple
You could simply define parameters by listing all parameters in parameters
list:
from alphaz.utils.api import route, api, Parameter
@route("books", parameters=["name"])
def method_name():
return "Book name is %s or %s"%(api["name"], api.get("name",default=""))
Parameter value is accessed by api
instance, using get
method, they could also be accessed using get_parameters
method from api
instance.
Object
Or you could use the Parameter
class to specify properties such as:
- ptype: value type int, str, bool,
SqlAlchemy model
- parameter is
automatically converted
to the specified type - if conversion failed an
exception
is raised - required: the parameter is required or not
- default: default parameter value
- options: authorized values
- mode: input mode
- cacheable: parameter is taken into acount in the caching system or not
- private: parameter is hiden from documentation or not
@route("/logs",
parameters = [
Parameter('page',required=True,ptype=int),
Parameter('startDate',required=True),
Parameter('endDate',default=None),
Parameter('error', options=["Y","N"])
])
def admin_logs():
return get_logs(**api.get_parameters())
Promote this method as it allows a better control on parameters
SqlAlchemy model
If you specify a SqlAlchemy model
as a type it will be automatically converted to the specified model.
from core import core
db = core.db
class Logs(db.Model, AlphaTable):
__tablename__ = 'LOGS'
id = AlphaColumn(Integer,nullable=False,primary_key=True)
name = AlphaColumn(String,nullable=False)
@route("logs",
parameters = [
Parameter('log',ptype=Logs)
])
def admin_logs():
db.add(api['log'])
Methods
Methods are specified the same way as in Flask
, using methods
parameter:
@route('logs', methods=["GET"])
def get_logs():
return db.select(Logs)
@route('logs', methods=["POST"])
def set_logs():
return db.add(Logs)
Methods can be managed using different routes
or within a single route
:
@route('logs', methods=["GET", "POST", "DELETE"])
def get_logs():
if api.is_get():
return db.select(Logs)
elif api.is_post():
return db.add(Logs)
elif api.is_delete():
return db.delete(Logs)
Authorizations
Route can be protected using the login system or admin rights.
Login system
To protect a route using the login system you must specify: logged=True
@route('protected', logged=True)
def protected_route():
user = api.get_logged_user()
return user
User information can be accessed using get_logged_user method.
Cache
A cache system is implemented, in order to use it you must specify the
Admin
In progress
Issues
In progress
Database alias
In progress
label_length