Welcome to apicore’s documentation!¶
Set of core libraries usefull for building REST API and Microservices based on Flask.
The code is open source, release under MIT and written in Python 3.
apt-get install build-essential python3-dev
pip install apicore
Features¶
- Cross-origin resource sharing (CORS) ready
- Data caching with redis server or direct in memory
- Configuration file loader
- A simple Logger
- Raise exception conform to HTTP status codes
- Authorization using JSON Web Token(JWT) issued from an OpenID Connect provider
- OpenAPI 3.0 specification embedded with Swagger UI
Example¶
#!/usr/bin/env python
from apicore import api, Logger, config, Http409Exception, Authorization
Logger.info("Starting {} API Server...".format(config.app_name))
@api.route('/error/')
def error():
"""
summary: Raise an execption
responses:
409:
description: Conflict
"""
raise Http409Exception()
@api.route('/jwt/')
def jwt():
userProfile = Authorization()
print(userProfile);
return "JWT Valid!"
if __name__ == "__main__":
api.debug = config.debug
api.run()
Configuration¶
Configuration is set in conf/config.yaml
file (see apicore.config.Config
).
Name | Default value | Description |
---|---|---|
app_name | “Meezio” | Application’s name. |
debug | True | Active debug mode. |
issWhitelist | None | Whitelist for OIDC issuers. If not set, every issuers are allowed except ones from blacklist. |
issBlacklist | None | Blacklist for OIDC issuers. synaxte : same as ‘iss’ claim in the JWT. |
prefix | “” | Add a prefix to URL path (ie: “/api”). |
redis | None | Redis server used for caching data : redis://:password@localhost:6379/0. If not set use memory. |
smtp_host | “localhost” | SMTP server used to sent email. |
swagger_ui | “/” | Relative URL path to embedded Swagger UI (prefix + swagger_ui ). |
tokenExpire | True | Check ‘exp’ claim in JWT to validate token. |
OpenAPI 3.0¶
- See specification for syntax.
- Document route’s methods with Operation Object using yaml syntax.
- Document your API in
conf/openapi.yaml
file. - Access your documentation through a python dictionary :
api.oas.specs
. - Your spec is available at
http[s]://<hostname>/openapi.json
. - Default path to
http[s]://<hostname>/
to see your spec with Swagger UI (setswagger_ui
inconf/config.yaml
to change path) - Full exemple :
@api.route('/sellers/<idseller>/', methods=['GET', 'PUT'])
def seller(idseller):
"""
description: "Path Item Object" level here, only common_responses is added to OpenAPi specification. Next level are "Operation Object".
parameters:
- name: idseller
in: path
description: uuid of seller
required: true
type: string
format: uuid
common_responses:
400:
description: Invalid request
401:
description: Authentification required
403:
description: Ressource access denied
500:
description: Server internal error
---
tags:
- profile
summary: Find a seller profile by ID
responses:
200:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Seller'
404:
description: Ressource does not exist
406:
description: Nothing to send maching Access-* headers
---
tags:
- profile
summary: Update seller profile
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Seller'
required: true
responses:
200:
description: Success
"""
pass
print(api.oas.spec)
APIs¶
Todo
- i18n HTTP response messages.
- Configure using command line argument and environnement variables which override configuration file.