Welcome to apicore’s documentation!¶
Set of core libraries for building REST API and Microservices based on Flask.
The code is open source, release under MIT and written in Python 3.
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
- OpenAPI 3.0 specification embedded with Swagger UI
Example¶
#!/usr/bin/env python
from apicore import api, Logger, config, Http409Exception
Logger.info("Starting {} API Server...".format(config.app_name))
@api.route('/error/')
def error():
"""
summary: Raise an execption
responses:
409:
description: Conflict
"""
raise Http409Exception()
if __name__ == "__main__":
# api is an instance of API which inherit from Flask
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 | “My App” | Application’s name. |
debug | True | Active debug mode. |
prefix | “” | Add a prefix to all URL paths (ie: “/api”). |
redis | None | Redis server used for caching data : redis://:password@localhost:6379/0. If not set use in-memory. |
swagger_ui | “/” | Relative URL path to embedded Swagger UI (prefix + swagger_ui ). |
specs_login | None | Login to access API Specification (openapi.json ), no Authentification by default. |
specs_pwd | None | Password to access API Specification. |
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.
- Add namespace for cache
- Configure using command line argument and environnement variables which override configuration file and making it optional.
- Use API Specification and json schemas to validate JSON data
- Access Control Policies engine
- MongoDB helpers
- Extensible notification system (using mail, Firebase, SMS, …)